etassia 0.1.0

data/lib/etassia/notation/plantuml/activity/bar_columns.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Where a bar stands: it hangs over the branches it joins, and a
+        # decision whose branch starts with one aims at the middle of them.
+        class BarColumns
+          # How far a bar reaches past the boxes it joins; PlantUML leaves 12
+          # on the left and 14 on the right.
+          OVERHANG = 13.0
+
+          def initialize(diagram, ranking, columns, boxes)
+            @diagram = diagram
+            @ranking = ranking
+            @columns = columns
+            @boxes = boxes
+          end
+
+          # @return [Array<Node>] the nodes on the side of the bar where
+          #   several branches meet it, or all its neighbours when no side
+          #   has more than the other
+          def fan(bar)
+            sides = joined(bar).group_by do |node|
+              @ranking.rank[node] <=> @ranking.rank[bar]
+            end.values
+            widest = sides.map(&:size).max
+            sides.select { |side| side.size == widest }.flatten
+          end
+
+          # @return [Array<Array>, nil] the columns of the boxes a bar fans
+          #   out to or gathers; nil for any other node
+          def fan_keys(node)
+            return unless node.kind == :bar
+
+            fan(node).map { |other| @columns.key[other] }
+          end
+
+          # Gives the outermost columns a bar joins room for its overhang.
+          # @param reach [Reach]
+          def widen(reach)
+            @diagram.nodes.select { |n| n.kind == :bar }.each do |bar|
+              widen_bar(reach, bar)
+            end
+            reach
+          end
+
+          private
+
+          def widen_bar(reach, bar)
+            boxes = fan(bar).map { |n| [@columns.key[n], n] }
+            return if boxes.empty?
+
+            overhang(reach, boxes.min_by(&:first), 0)
+            overhang(reach, boxes.max_by(&:first), 1)
+          end
+
+          def overhang(reach, (key, node), side)
+            reach.grow(key, @ranking.row(node), side,
+                       (@boxes[node].width / 2.0) + OVERHANG)
+          end
+
+          def joined(bar)
+            @diagram.edges.filter_map do |edge|
+              other = edge.from.equal?(bar) ? edge.to : edge.from
+              other if (edge.from.equal?(bar) || edge.to.equal?(bar)) &&
+                other.kind != :bar
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/box.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Where a node sits: its centre and size.
+        class Box
+          attr_accessor :cx, :cy, :width, :height
+          # @return [Float, nil] where arrows meet a bar that has one
+          #   neighbour on a side; nil elsewhere
+          attr_writer :anchor
+          # @return [Array<Box>] the boxes a bar fans out to or gathers
+          attr_accessor :fan
+
+          # @return [Float] where a lone neighbour's arrow meets the box
+          def anchor
+            @anchor || cx
+          end
+
+          def initialize(width:, height:)
+            @width = width
+            @height = height
+            @cx = 0.0
+            @cy = 0.0
+          end
+
+          # @return [Box] the box with these edges
+          def self.spanning(left, top, right, bottom)
+            new(width: right - left, height: bottom - top).tap do |box|
+              box.cx = (left + right) / 2.0
+              box.cy = (top + bottom) / 2.0
+            end
+          end
+
+          # @return [Boolean] whether the vertical at x runs through the box
+          def spans?(x_pos)
+            left < x_pos && x_pos < right
+          end
+
+          def left
+            cx - (width / 2.0)
+          end
+
+          def right
+            cx + (width / 2.0)
+          end
+
+          def top
+            cy - (height / 2.0)
+          end
+
+          def bottom
+            cy + (height / 2.0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "node"
+require_relative "edge"
+require_relative "note"
+require_relative "diagram"
+require_relative "../unsupported_construct_error"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Accumulates the nodes and edges both syntaxes parse into, and the
+        # swimlane and partition a new node belongs to.
+        class Builder
+          attr_reader :nodes, :edges
+          attr_accessor :title
+
+          def initialize
+            @nodes = []
+            @edges = []
+            @lanes = []
+            @lane = nil
+            @partition = nil
+            @warnings = []
+          end
+
+          # Records a notice PlantUML prints above the diagram, such as the
+          # old `#colour:` action syntax.
+          def warn(message)
+            @warnings << message
+          end
+
+          # @return [Node]
+          def node(kind, text: nil, fill: nil, bare: false)
+            Node.new(id: "n#{@nodes.size}", kind: kind, text: text,
+                     fill: fill, bare: bare).tap { |n| enrol(n) }
+          end
+
+          # @return [Edge]
+          def connect(from, to, **options)
+            Edge.new(from: from, to: to, **options).tap { |e| @edges << e }
+          end
+
+          def lane(name, colour)
+            @lanes << [name, colour] unless @lanes.any? { |n, _| n == name }
+            @lane = name
+          end
+
+          # @param name [String, nil] nil leaves the partition
+          def partition(name, line: 0, text: "")
+            if name && @partition
+              raise UnsupportedConstructError.new(
+                construct: "nested partition", line: line, text: text,
+              )
+            end
+            @partition = name
+          end
+
+          # @return [Diagram]
+          def diagram
+            Diagram.new(nodes: @nodes, edges: @edges, lanes: @lanes,
+                        title: @title, warnings: @warnings)
+          end
+
+          private
+
+          def enrol(node)
+            node.lane = @lane
+            node.partition = @partition
+            @nodes << node
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/canvas.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative "../../../text_measurement"
+require_relative "mark"
+require_relative "metrics"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Collects {Mark}s in drawing order and the extent they reach.
+        class Canvas
+          INK = "#181818"
+          MONO_SIZE = 10
+
+          # @return [Array<Mark>]
+          attr_reader :marks
+          # @return [Float] the leftmost x any mark reaches
+          attr_reader :min_x
+          # @return [Float] the rightmost x any mark reaches
+          attr_reader :max_x
+          # @return [Float] the lowest y any mark reaches
+          attr_reader :max_y
+
+          # @param metrics [Metrics] the font sizes of the roles
+          def initialize(metrics = Metrics.new)
+            @metrics = metrics
+            @marks = []
+            @min_x = Float::INFINITY
+            @max_x = 0.0
+            @max_y = 0.0
+          end
+
+          def add(kind, **attrs)
+            @marks << Mark.new(kind, **attrs)
+          end
+
+          def see(left, right, bottom)
+            @min_x = [@min_x, left].min
+            @max_x = [@max_x, right].max
+            @max_y = [@max_y, bottom].max
+          end
+
+          # `role` names the `<style>` selector that restyles the mark:
+          # :partition, :diamond, :note or :arrow; nil is a plain action.
+          #
+          # @param box [Box]
+          def rect(box, fill:, radius: nil, role: nil, stroke: INK)
+            see(box.left, box.right, box.bottom)
+            add(:rect, x: box.left, y: box.top, width: box.width,
+                       height: box.height, fill: fill, stroke: stroke,
+                       rx: radius, role: role)
+          end
+
+          # @param box [Box]
+          def polygon(points, fill:, stroke: INK, role: nil)
+            points.each { |x_pos, y_pos| see(x_pos, x_pos, y_pos) }
+            add(:polygon, points: points, fill: fill, stroke: stroke,
+                          role: role)
+          end
+
+          def circle(box, radius, fill:, role: nil, width: 1)
+            see(box.left, box.right, box.bottom)
+            add(:circle, cx: box.cx, cy: box.cy, r: radius, fill: fill,
+                         stroke: "#222222", role: role, width: width)
+          end
+
+          def path(points, stroke:, width: 1.0, dash: nil, curve: false)
+            points.each { |x_pos, y_pos| see(x_pos, x_pos, y_pos) }
+            add(:path, points: points, stroke: stroke, width: width,
+                       dash: dash, curve: curve)
+          end
+
+          # One text mark per line, the first baseline at `point`.
+          def lines(rows, point, anchor: "start", role: nil, **face)
+            face = { size: @metrics.size(role), **face }
+            rows.each_with_index do |content, index|
+              y_pos = point.last + (index * @metrics.line_height(role))
+              text([point.first, y_pos], content, anchor,
+                   face.merge(role: role))
+            end
+          end
+
+          # @return [Float] the width of the widest of the monospace rows
+          def mono_width(rows)
+            rows.map do |row|
+              TextMeasurement.measure(row, font_size: MONO_SIZE,
+                                           monospace: true)[:width]
+            end.max
+          end
+
+          # Monospace notice lines, `pitch` apart.
+          def mono_lines(rows, point, pitch:)
+            rows.each_with_index do |content, index|
+              add(:text, x: point.first, y: point.last + (index * pitch),
+                         content: content, anchor: "start", size: MONO_SIZE,
+                         family: "monospace", role: nil)
+            end
+          end
+
+          private
+
+          def text(point, content, anchor, face)
+            size = face[:size]
+            role = face[:role]
+            width = @metrics.text_width([content], role: role, size: size)
+            left = point.first - (width * { "start" => 0, "middle" => 0.5,
+                                            "end" => 1 }.fetch(anchor))
+            see(left, left + width, point.last + 3)
+            add(:text, x: point.first, y: point.last, content: content,
+                       anchor: anchor, **face)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/column_centres.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Where each column's centre falls. Columns stand left to right,
+        # each as wide as what reaches out of it. A decision's own column is
+        # a trunk: it takes no room and hangs midway between its first and
+        # last branch, and those branches stand a hexagon's width and a gap
+        # apart at least.
+        class ColumnCentres
+          COLUMN_GAP = 20.0
+          LANE_GAP = 30.0
+          # What a label's far end adds to the block a wide decision centres on.
+          LABEL_PAD = 3.5
+
+          # @param reach [Hash{Array => Array(Float, Float)}] how far each
+          #   column reaches left and right of its centre
+          def initialize(columns, boxes, reach, margin, bars)
+            @columns = columns
+            @boxes = boxes
+            @spread = reach.row_spread(margin)
+            @reach = reach.columns
+            @margin = margin
+            @bars = bars
+            @trunks = columns.spans.keys.group_by { |node| columns.key[node] }
+          end
+
+          # @param keys [Array<Array>] every column key, in order
+          # @return [Hash{Array => Float}]
+          def call(keys)
+            placed = settle(keys - @trunks.keys)
+            keys.to_h { |key| [key, placed[key] || trunk_centre(key, placed)] }
+          end
+
+          private
+
+          # Spreads the solid columns, moving some right until every
+          # decision's branches stand far enough apart.
+          def settle(solid)
+            extra = Hash.new(0.0)
+            placed = spread(solid, extra)
+            (solid.size * 2).times do
+              deficit = branch_deficit(placed, solid) ||
+                lane_deficit(placed, solid) or break
+              extra[deficit.first] += deficit.last
+              placed = spread(solid, extra)
+            end
+            placed
+          end
+
+          def spread(solid, extra)
+            return spread_columns(solid, extra) unless @spread
+
+            @spread.call(solid) { |prior, key| gap(prior, key, extra) }
+          end
+
+          def spread_columns(solid, extra)
+            cursor = @margin
+            solid.each_with_index.to_h do |key, index|
+              cursor += gap(solid[index - 1], key, extra) if index.positive?
+              centre = cursor + @reach[key].first
+              cursor = centre + @reach[key].last
+              [key, centre]
+            end
+          end
+
+          def gap(previous, key, extra)
+            COLUMN_GAP + (previous.first == key.first ? 0 : LANE_GAP) +
+              extra[key]
+          end
+
+          # The first column that has to move right so that some decision's
+          # branches stand apart, and by how much.
+          def branch_deficit(placed, solid)
+            @columns.spans.each do |node, (first, last)|
+              short = shortfall(node, first, last, placed)
+              edge = (@bars.fan_keys(first) || [@columns.key[first]]).max
+              anchor = solid.find { |key| (key <=> edge).positive? }
+              return [anchor, short] if short.positive? && anchor
+            end
+            nil
+          end
+
+          # The first column of a lane that has to move right so that the
+          # lane before it, its decisions centred on branches in this one
+          # included, ends before its band begins.
+          def lane_deficit(placed, solid)
+            solid.each_cons(2) do |prior, key|
+              next if prior.first == key.first
+
+              short = lane_reach(prior.first, placed) +
+                (2 * Placement::BAND_PAD) -
+                (placed[key] - @reach[key].first)
+              return [key, short] if short.positive?
+            end
+            nil
+          end
+
+          def lane_reach(lane, placed)
+            (placed.keys + @trunks.keys).select { |key| key.first == lane }
+              .map { |key| centre(key, placed) + @reach[key].last }.max
+          end
+
+          def shortfall(node, left, right, placed)
+            @boxes[node].width + COLUMN_GAP -
+              (head_centre(right, placed) - head_centre(left, placed))
+          end
+
+          def centre(key, placed, seen = [])
+            placed.fetch(key) { trunk_centre(key, placed, seen) }
+          end
+
+          # Where the arrow into a branch lands: a bar takes it midway
+          # between the branches it fans out to.
+          def head_centre(node, placed, seen = [])
+            keys = @bars.fan_keys(node)
+            return centre(@columns.key[node], placed, seen) unless keys
+
+            keys.map { |key| centre(key, placed, seen) }.minmax.sum / 2.0
+          end
+
+          def trunk_centre(key, placed, seen = [])
+            return 0.0 if seen.include?(key)
+
+            seen += [key]
+            mids = @trunks.fetch(key).map { |node| mid(node, placed, seen) }
+            mids.sum / mids.size
+          end
+
+          def mid(node, placed, seen)
+            first, last = @columns.spans[node]
+            left = head_centre(first, placed, seen)
+            right = head_centre(last, placed, seen)
+            return (left + right) / 2.0 unless @columns.wide?(node)
+
+            block(first, last, [left, right]).sum / 2.0
+          end
+
+          # The edges of the steps a wide decision's branches stand in, the
+          # outer labels' width counted.
+          def block(first, last, heads)
+            [heads.first - @reach[@columns.key[first]].first,
+             heads.last + @reach[@columns.key[last]].last + LABEL_PAD]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/activity/columns.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Activity
+        # Gives each node a column. A walk down the forward edges keeps a
+        # node's first unplaced successor in its column and sends the others
+        # to fresh columns on its right, so branches do not cross the body
+        # they split from. With swimlanes a node sits in its lane's columns.
+        class Columns
+          # @return [Hash{Node => Array(Integer, Integer)}] lane index and
+          #   column inside the lane
+          attr_reader :key
+          # @return [Hash{Node => Array(Node, Node)}] for each decision that
+          #   splits into side by side branches, its first and last branch;
+          #   the decision's own column is a trunk hung between them
+          attr_reader :spans
+
+          # @return [Boolean] whether the decision splits three or more ways
+          def wide?(node)
+            @wide.include?(node)
+          end
+
+          def initialize(diagram, ranking)
+            @diagram = diagram
+            @ranking = ranking
+            @lane_names = diagram.lanes.map(&:first)
+            @key = {}.compare_by_identity
+            @taken = Set.new
+            @widest = Hash.new(-1)
+            start_branch_tables
+            place_all
+          end
+
+          private
+
+          def start_branch_tables
+            @last = Hash.new(-1)
+            @trunks = Set.new
+            @spans, @joins, @after = Array.new(3) { {}.compare_by_identity }
+            @wide = Set.new.compare_by_identity
+            @open = Set.new.compare_by_identity
+          end
+
+          def place_all
+            pending = @diagram.nodes.dup
+            until pending.empty?
+              node = pending.find { |n| ready?(n) } || pending.first
+              place(node, beside(node)) unless @key[node]
+              pending.reject! { |n| @key[n] }
+            end
+          end
+
+          # A node reached along a row waits for the node it lies beside.
+          def ready?(node)
+            level = level_in(node)
+            level.nil? || !@key[level.from].nil?
+          end
+
+          def level_in(node)
+            @ranking.level_in(node)
+          end
+
+          def beside(node)
+            edge = level_in(node)
+            return 0 unless edge && @key[edge.from]
+
+            column = @key[edge.from].last
+            step = @open.include?(edge.from) ? 0.5 : 1
+            edge.direction == :left ? column - step : column + step
+          end
+
+          def place(node, preferred)
+            lane = lane_of(node)
+            column = free_column(lane, preferred, @ranking.rank[node])
+            @key[node] = [lane, column]
+            @widest[lane] = [@widest[lane], column.ceil].max
+            note_depth(lane, column, @ranking.rank[node])
+            hang_branches(node, lane, column)
+            place_children(node, lane, column)
+          end
+
+          def place_children(node, lane, column)
+            heads = @spans[node]
+            keep = heads.nil?
+            @ranking.forward(node).each do |edge|
+              next if placed_or_held?(edge)
+
+              place(edge.to,
+                    preference(edge.to, [lane, column, keep], node, heads))
+              keep = false
+            end
+            close_branches(node, lane, column)
+          end
+
+          def placed_or_held?(edge)
+            @key[edge.to] || edge.level? || pending?(edge.to)
+          end
+
+          def preference(child, spot, node, heads)
+            lane, column, keep = spot
+            return column - 0.5 if heads && child.equal?(heads.first)
+            return 0 unless lane_of(child) == lane
+            return column if keep
+            return room_right(lane, column, child, @open.include?(node)) if
+              heads
+
+            @widest[lane] + 1
+          end
+
+          # The nearest column on the right that no step of an earlier part
+          # of the flow still reaches down to, and that no decision hangs
+          # from.
+          def room_right(lane, column, child, adjacent)
+            rank = @ranking.rank[child]
+            found = adjacent ? column + 0.5 : column.floor + 1
+            found += 1 while @trunks.include?([lane, found]) ||
+                @last[[lane, found]] >= rank ||
+                @taken.include?([lane, found, rank])
+            found
+          end
+
+          # The node where a decision's branches meet waits until they are
+          # all placed, then goes on the trunk.
+          def pending?(node)
+            @joins.key?(node)
+          end
+
+          def close_branches(node, _lane, column)
+            join = @after[node]
+            return unless join && !@key[join]
+
+            @joins.delete(join)
+            place(join, column)
+          end
+
+          # A decision with two or more branches of its own keeps its
+          # column for the flow that runs through it: its first branch
+          # takes the column on its left, the rest those on its right, and
+          # the node where they meet goes back to the trunk.
+          def hang_branches(node, lane, column)
+            heads = @ranking.forward(node).map(&:to)
+            join = split_join(node, heads)
+            return open_branches(node, heads, lane, column) unless join
+            return unless lane_of(join) == lane
+
+            hang(node, heads, lane, column)
+            @joins[join] = column
+            @after[node] = join
+          end
+
+          # A legacy decision of two steps that never meet, one of them
+          # parked beside it, hangs the same way: the steps stand either
+          # side of it, the parked one a half column away.
+          def open_branches(node, heads, lane, column)
+            return unless parked_pair?(node, heads)
+
+            @open << node
+            hang(node, heads, lane, column)
+          end
+
+          def parked_pair?(node, heads)
+            @diagram.legacy && forks?(node, heads) && heads.size == 2 &&
+              steps_with_parked?(heads)
+          end
+
+          def steps_with_parked?(heads)
+            heads.all? { |head| head.kind == :action } &&
+              heads.any? { |head| @ranking.parked?(head) }
+          end
+
+          def hang(node, heads, lane, column)
+            @spans[node] = [heads.first, heads.last]
+            @wide << node if heads.size > 2
+            @trunks << [lane, column]
+          end
+
+          # The merge that closes a decision with two or more branches of
+          # its own, when it has one.
+          def split_join(node, heads)
+            return unless forks?(node, heads)
+
+            join = join_of(heads)
+            join if join&.kind == :merge
+          end
+
+          def forks?(node, heads)
+            node.kind == :decision && heads.size > 1 &&
+              heads.none? { |head| head.kind == :merge }
+          end
+
+          def note_depth(lane, column, rank)
+            @last[[lane, column]] = [@last[[lane, column]], rank].max
+          end
+
+          # The first node every branch reaches, nearest first.
+          def join_of(heads)
+            common = heads.map { |head| downstream(head) }.reduce(:&)
+            common.min_by { |node| @ranking.rank[node] }
+          end
+
+          def downstream(node, seen = Set.new.compare_by_identity)
+            return seen unless seen.add?(node)
+
+            @ranking.forward(node).each { |edge| downstream(edge.to, seen) }
+            seen
+          end
+
+          def free_column(lane, preferred, rank)
+            column = preferred
+            column += 1 while @taken.include?([lane, column, rank])
+            @taken << [lane, column, rank]
+            column
+          end
+
+          def lane_of(node)
+            node.lane ? @lane_names.index(node.lane) : -1
+          end
+        end
+      end
+    end
+  end
+end