etassia 0.1.0

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative "plane"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Where {Routes} slides a transition's label along its chord, away
+        # from container titles and from the state many transitions meet at.
+        module LabelClearance
+          CHORD_STEPS = 40
+          CROWD = 4
+          CROWD_SHIFT = 0.15
+          TITLE_BAND = 30.0
+          ALONG = [0.4, 0.6, 0.3, 0.7, 0.2, 0.8, 0.1, 0.9].freeze
+          private_constant :CHORD_STEPS, :CROWD, :CROWD_SHIFT, :TITLE_BAND,
+                           :ALONG
+
+          private
+
+          # The label's spot, moved along the route to the nearest one that
+          # is off every container's title, every state and every label
+          # already placed; the first spot when none is.
+          def settled(spot, points, label)
+            return spot unless spot
+
+            found = [spot, *spots_along(points, label)].find do |at|
+              free?(rect_at(at, label))
+            end || spot
+            @placed << rect_at(found, label)
+            found
+          end
+
+          def rect_at(spot, label)
+            half = [label[:width], label[:height]].map { |size| size / 2.0 }
+            Plane.around(spot.values_at(:x, :y), half)
+          end
+
+          def free?(rect)
+            fenced = Plane.grow(rect, 3)
+            (@placed + obstacles).none? { |other| Plane.meet?(fenced, other) }
+          end
+
+          # Each container's title band and each state that holds nothing.
+          def obstacles
+            @obstacles ||= @boxes.values.reject { |box| note_box?(box) }
+              .map { |box| title_band(box) }
+          end
+
+          def title_band(box)
+            rect = Plane.rect(box)
+            return rect unless box.node[:children]&.any?
+
+            [rect[0], rect[1], rect[2], rect[1] + TITLE_BAND]
+          end
+
+          def spots_along(points, label)
+            ALONG.flat_map do |fraction|
+              at, from, to = Plane.at_length(points, fraction)
+              sides(at, steep?(from, to), label)
+            end
+          end
+
+          def sides(at, steep, label)
+            reach = steep ? (label[:width] / 2.0) + RouteGeometry::LABEL_GAP : 0
+            lift = steep ? 0 : (label[:height] / 2.0) + RouteGeometry::LABEL_GAP
+            [{ x: at.first + reach, y: at.last - lift },
+             { x: at.first - reach, y: at.last + lift }]
+          end
+
+          # @return [Hash{String=>Integer}] how many transitions meet at
+          #   each state
+          def degrees(edges)
+            edges.each_with_object(Hash.new(0)) do |edge, found|
+              ends = [edge[:sources].first, edge[:targets].first].uniq
+              ends.each { |id| found[id] += 1 } if ends.size == 2
+            end
+          end
+
+          # The route moved along its chord so its label sits where the
+          # chord is outside the containers of both ends, not over a
+          # container's title, and away from a crowded end.
+          def clear_of_containers(edge, points)
+            slide = clear_middle(edge, points) + crowd_bias(edge) - 0.5
+            return points if slide.zero?
+
+            along = chord(points).map { |run| run * slide }
+            points.map { |point| point.zip(along).map(&:sum) }
+          end
+
+          def chord(points)
+            points.last.zip(points.first).map { |to, from| to - from }
+          end
+
+          # @return [Float] the middle, as a fraction of the chord, of the
+          #   stretch outside both ends' containers; 0.5 when there is none
+          def clear_middle(edge, points)
+            boxes = foreign_containers(edge)
+            steps = (0..CHORD_STEPS).map { |step| step.fdiv(CHORD_STEPS) }
+            clear = steps.select { |at| open?(boxes, points, at) }
+            return 0.5 if boxes.empty? || clear.size < 2
+
+            (clear.first + clear.last) / 2.0
+          end
+
+          def open?(boxes, points, at)
+            spot = points.first.zip(chord(points)).map do |from, run|
+              from + (run * at)
+            end
+            boxes.none? { |box| holds?(box, spot) }
+          end
+
+          # A label moves toward the far end of a chord that leaves or
+          # reaches a state many transitions meet at.
+          def crowd_bias(edge)
+            out = @degree[edge[:sources].first]
+            into = @degree[edge[:targets].first]
+            return 0.0 if [out, into].max < CROWD
+
+            out > into ? CROWD_SHIFT : -CROWD_SHIFT
+          end
+
+          # The boxes around only one end of the edge.
+          def foreign_containers(edge)
+            source = ancestors(edge[:sources].first)
+            target = ancestors(edge[:targets].first)
+            (source - target) + (target - source)
+          end
+
+          def ancestors(id)
+            found = []
+            while (owner = @parent[id])
+              found << @boxes.fetch(owner)
+              id = owner
+            end
+            found
+          end
+
+          def holds?(box, spot)
+            spot.first.between?(box.x, box.x + box.w) &&
+              spot.last.between?(box.y, box.y + box.h)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "routes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # How far right a container must reach to hold the labels of the
+        # transitions between its members. Graphviz makes each label a node
+        # of the rank between the two states it joins, so the labels of one
+        # rank stand side by side and the cluster grows to hold them, which a
+        # layout that only sees the states does not.
+        class LabelReach
+          # The room graphviz keeps between two nodes of a rank.
+          GAP = 18.0
+          # The room between the last label and the cluster's border.
+          MARGIN = 12.5
+          private_constant :GAP, :MARGIN
+
+          # @param edges [Array<Hash>] every transition of the graph
+          # @param parent [Hash{String=>String}] the container of each state
+          def initialize(edges, parent)
+            @edges = edges.select { |edge| Array(edge[:labels]).any? }
+            @parent = parent
+          end
+
+          # @param members [Array<Hash>] the placed states of a container,
+          #   positioned relative to it
+          # @return [Float] the width the container needs for its labels
+          def width(members)
+            ranks = by_rank(members)
+            return 0.0 if ranks.empty?
+
+            ranks.values.map { |labels| placed(labels).last }
+              .map { |label, left| left + label.width }.max + MARGIN
+          end
+
+          # Where the labels of a rank shared by two or more transitions
+          # stand, so each takes its own slot of the rank between its states.
+          #
+          # @param members [Array<Hash>] as for {#width}
+          # @return [Array<Array(Hash, Hash)>] each such transition and its
+          #   label centre and the x its line bends through, relative to the
+          #   container
+          def slots(members)
+            ranks = by_rank(members).values.map { |all| all.select(&:direct) }
+            ranks = ranks.select { |labels| labels.size > 1 }
+            ranks.flat_map { |labels| centres(labels) }
+          end
+
+          private
+
+          Label = Struct.new(:edge, :ideal, :width, :row, :down, :direct)
+          private_constant :Label
+
+          # The labels of each rank, in the order their edges were drawn.
+          def by_rank(members)
+            by_id = members.to_h { |node| [node[:id], node] }
+            joined = @edges.filter_map { |edge| joint(edge, by_id) }
+            joined.group_by(&:first).transform_values do |rows|
+              rows.map(&:last)
+            end
+          end
+
+          # The rank key and the label of an edge between two members.
+          def joint(edge, by_id)
+            pair = Routes.level_pair(edge, @parent, by_id.keys)
+            return unless pair
+
+            from, to = pair.map { |id| by_id.fetch(id) }
+            upper, lower = [from, to].sort_by { |node| node[:y] }
+            [upper[:y] + upper[:height], label(edge, from, to, upper, lower)]
+          end
+
+          def label(edge, from, to, upper, lower)
+            Label.new(edge, middle(from, to) + 1, edge[:labels].first[:width],
+                      rank_middle(upper, lower), upper.equal?(from),
+                      direct?(edge, from, to))
+          end
+
+          # Whether the edge joins the two members themselves, not states
+          # inside them.
+          def direct?(edge, from, to)
+            edge.values_at(:sources, :targets).flatten == [from[:id], to[:id]]
+          end
+
+          # The row halfway across the gap between the two states.
+          def rank_middle(upper, lower)
+            bottom = upper[:y] + upper[:height]
+            bottom + ((lower[:y] - bottom) / 2.0)
+          end
+
+          def middle(from, to)
+            centres = [from, to].map { |node| node[:x] + (node[:width] / 2.0) }
+            centres.sum / 2.0
+          end
+
+          # The group is centred on where its transitions meant to stand,
+          # but never left of the container's own edge.
+          def centres(labels)
+            row = placed(labels)
+            slide = slide_for(row, labels)
+            row.map do |label, left|
+              [label.edge, { x: left + slide + (label.width / 2.0),
+                             y: label.row, via: left + slide }]
+            end
+          end
+
+          def slide_for(row, labels)
+            first = row.first.last
+            middle = labels.sum(&:ideal) / labels.size
+            [middle - (span(row) / 2.0), 0.0].max - first
+          end
+
+          def span(row)
+            last, left = row.last
+            left + last.width - row.first.last
+          end
+
+          # Each label of a rank with its left edge: side by side from the
+          # ideal spot, those of edges that run down before those that run
+          # up.
+          def placed(labels)
+            ordered = labels.sort_by.with_index do |label, index|
+              [label.ideal, label.down ? 0 : 1, index]
+            end
+            right = 0.0
+            ordered.map do |label|
+              left = [label.ideal, right + GAP].max
+              right = left + label.width
+              [label, left]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require_relative "../../../layout/state_diagram"
+require_relative "hierarchy"
+require_relative "look"
+require_relative "curve"
+require_relative "extent"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # The state layout for PlantUML's reading of a state diagram. The
+        # Mermaid layout it extends places a composite as one box with its
+        # children on top of the name and its transitions as lines between
+        # centres; this one sizes each composite from its content, puts the
+        # name in a header, and routes transitions between borders.
+        class Layout < Etassia::Layout::StateDiagram
+          # The engine builds a layout with `new` only, so a diagram's flat
+          # transitions travel in a class that builds it.
+          Flat = Struct.new(:pairs) do
+            def new
+              Layout.new.tap { |layout| layout.flat = pairs }
+            end
+          end
+          private_constant :Flat
+
+          # @param pairs [Array<Array(String, String)>] the transitions
+          #   PlantUML draws on one rank
+          # @return [#new] builds a layout that keeps them on one rank
+          def self.with_flat(pairs)
+            Flat.new(pairs)
+          end
+
+          attr_writer :flat
+
+          private
+
+          def scene(diagram)
+            graph = build_graph(diagram)
+            Hierarchy.new(graph, @flat || []).place
+            scene_from_graph(graph)
+          end
+
+          # What the diagram draws, apart from Mermaid's reading: a history
+          # state is a circle.
+          def state_shape_type(state)
+            return "history" if history?(state)
+
+            super
+          end
+
+          # The canvas ends a margin past the last box, route or label, as
+          # PlantUML's does, not past a fixed padding.
+          def scene_geometry(graph)
+            width, height = Extent.of(graph).map { |far| far + Look::CANVAS_MARGIN }
+            { width: width, height: height,
+              view_box: "0 0 #{width} #{height}" }
+          end
+
+          def history?(state)
+            %w[H H*].include?(state.label) &&
+              state.id.to_s.match?(/_(?:deep_)?history\z/)
+          end
+
+          def dimensions_for_shape(state, label_dims, descriptions)
+            case state_shape_type(state)
+            when "history" then Look::HISTORY_SIZE
+            when "start", "end" then Look.terminal(state_shape_type(state))
+            when "note" then note_dimensions(state)
+            else leaf_dimensions(state, label_dims, descriptions)
+            end
+          end
+
+          def add_terminal_radius(metadata)
+            radius = Look::TERMINAL_RADIUS[metadata[:shape_type]]
+            metadata[:shape_radius] = radius if radius
+            metadata
+          end
+
+          def note_dimensions(state)
+            lines = state_texts(state)
+            widest = lines.map do |line|
+              measure_text(line, font_size: Look::NOTE_FONT)[:width]
+            end.max.to_f
+            { width: widest + Look::NOTE_PAD_X + Look::NOTE_PAD_RIGHT,
+              height: (lines.size * Look::NOTE_LINE) + (2 * Look::NOTE_PAD_Y) }
+          end
+
+          # A plain state is a name above a divider; a composite is sized
+          # from its children later.
+          def leaf_dimensions(state, label_dims, descriptions)
+            if state.children.any?
+              return calculate_normal_state_dimensions(state, label_dims,
+                                                       descriptions)
+            end
+
+            lines = descriptions.map do |text|
+              measure_text(text, font_size: Look::TEXT_FONT)[:width]
+            end
+            { width: ([label_dims[:width]] + lines).max + 20.0,
+              height: leaf_height(descriptions.size) }
+          end
+
+          def leaf_height(lines)
+            body = (lines * Look::TEXT_LINE) + 10
+            body = Look::EMPTY_BODY if lines.zero?
+            Look::LEAF_BAR + body
+          end
+
+          # A composite's name is its header, not its centre; a start or end
+          # marker carries no text.
+          def typed_labels(state)
+            case state.dig(:metadata, :shape_type)
+            when "start", "end" then []
+            when "note" then note_labels(state)
+            when "history" then super
+            else titled_labels(state)
+            end
+          end
+
+          def titled_labels(state)
+            name, *rest = state[:labels]
+            bar = Array(state[:children]).empty? ? Look::LEAF_BAR : Look::BAR
+            [text_label(name, state[:x] + (state[:width] / 2.0),
+                        state[:y] + (bar / 2.0)),
+             *body_labels(state, rest, bar)]
+          end
+
+          def body_labels(state, lines, bar)
+            lines.each_with_index.map do |line, index|
+              text_label(line, state[:x] + Look::TEXT_PAD,
+                         state[:y] + bar + 13.0 + (index * Look::TEXT_LINE))
+            end
+          end
+
+          def note_labels(state)
+            state[:labels].each_with_index.map do |line, index|
+              text_label(
+                line, state[:x] + Look::NOTE_PAD_X,
+                state[:y] + Look::NOTE_PAD_Y + (Look::NOTE_LINE / 2.0) +
+                (index * Look::NOTE_LINE), size: Look::NOTE_FONT
+              )
+            end
+          end
+
+          def text_label(line, x_position, y_position, size: Look::TEXT_FONT)
+            Etassia::Layout::StateDiagram::Label.new(
+              text: line[:text], width: line[:width], height: line[:height],
+              x: x_position, y: y_position, font_size: size
+            )
+          end
+
+          def section_path(section)
+            Curve.path([section.start_point, *section.bend_points,
+                        section.end_point])
+          end
+
+          def typed_edge_labels(edge, _source, _target)
+            label = (edge[:labels] || []).first
+            return [] unless label && edge[:label_at]
+
+            [Etassia::Layout::StateDiagram::Label.new(
+              text: label[:text], width: label[:width],
+              height: label[:height], x: edge[:label_at][:x],
+              y: edge[:label_at][:y], font_size: small_font_size
+            )]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "routes"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # The transitions one container's layout is given, as joins between
+        # its rows. A transition between composites that share ranks is left
+        # out, so it does not stack them.
+        class LevelEdges
+          # @param edges [Array<Hash>] every transition of the graph
+          # @param parent [Hash{String=>String}] the container of each state
+          # @param ranking [Ranking]
+          def initialize(edges, parent, ranking)
+            @edges = edges
+            @parent = parent
+            @ranking = ranking
+          end
+
+          # @param rows [Array<Row>] the container's rows
+          # @return [Array<Hash>] ELK edges between row ids
+          def of(rows)
+            unit = unit_ids(rows)
+            kept, peers = joins(unit).partition do |_, pair|
+              !@ranking.overlap?(*pair)
+            end
+            elk = elk_edges(majority(kept), unit)
+            joined = elk + entries(elk, peer_pairs(peers, unit))
+            peers.empty? ? joined : by_target(joined, rows)
+          end
+
+          def elk_edges(joined, unit)
+            joined.filter_map { |edge, pair| elk_edge(edge, pair, unit) }
+          end
+
+          def peer_pairs(peers, unit)
+            peers.map { |_, pair| pair.map { |id| unit[id] } }
+          end
+
+          # Edges into the rows listed first come first, so ELK places
+          # those rows first.
+          def by_target(edges, rows)
+            ids = rows.map(&:id)
+            edges.sort_by.with_index do |edge, at|
+              [ids.index(edge[:targets].first), at]
+            end
+          end
+
+          # @param rows [Array<Row>] the container's rows
+          # @return [Array<String>] the ids of rows PlantUML draws beside a
+          #   row one of its transitions joins, in the order given
+          def peer_ids(rows)
+            unit = unit_ids(rows)
+            linked = joins(unit).map(&:last).select do |pair|
+              @ranking.overlap?(*pair)
+            end
+            rows.map(&:id) & linked.flatten.map { |id| unit[id] }
+          end
+
+          private
+
+          # Of two states joined both ways, graphviz keeps the way most
+          # transitions run and reverses the rest, so the states rank by the
+          # majority; an even split keeps both.
+          def majority(joined)
+            counts = joined.map(&:last).tally
+            joined.reject do |_, pair|
+              counts[pair] < counts.fetch(pair.reverse, 0)
+            end
+          end
+
+          def unit_ids(rows)
+            rows.each_with_object({}) do |row, found|
+              row.nodes.each { |node| found[node[:id]] = row.id }
+            end
+          end
+
+          def joins(unit)
+            @edges.filter_map do |edge|
+              pair = Routes.level_pair(edge, @parent, unit.keys)
+              [edge, pair] if pair
+            end
+          end
+
+          def elk_edge(edge, pair, unit)
+            from, to = pair.map { |id| unit[id] }
+            return if from == to
+
+            { id: edge.object_id.to_s, sources: [from], targets: [to] }
+          end
+
+          # A composite with nothing leading to it enters at the rank of
+          # the peer it stands beside.
+          def entries(elk, peers)
+            peers.flat_map { |pair| [pair, pair.reverse] }
+              .flat_map { |mine, other| enter(elk, mine, other) }
+          end
+
+          def enter(elk, mine, other)
+            return [] if elk.any? { |found| found[:targets] == [mine] }
+
+            elk.select { |found| found[:targets] == [other] }.map do |found|
+              { id: "#{found[:id]}>#{mine}", sources: found[:sources],
+                targets: [mine] }
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # The measures of PlantUML 1.2026.6's state drawing, read from its
+        # SVG, and the curve a transition is drawn as.
+        module Look
+          TEXT_FONT = 14.0
+          TEXT_LINE = 16.49
+          TEXT_PAD = 6.0
+          LEAF_BAR = 26.49
+          BAR = 22.0
+          EMPTY_BODY = 23.51
+          NOTE_FONT = 13.0
+          NOTE_LINE = 15.31
+          NOTE_PAD_X = 6.0
+          NOTE_PAD_RIGHT = 15.0
+          NOTE_PAD_Y = 5.0
+          CANVAS_MARGIN = 20.0
+          FOLD = 10.0
+          TAIL = 4.0
+          HISTORY_SIZE = { width: 22.0, height: 22.0 }.freeze
+          TERMINAL_RADIUS = { "start" => 10.0, "end" => 11.0 }.freeze
+
+          # @return [Hash] a start or end marker's width and height
+          def self.terminal(kind)
+            size = TERMINAL_RADIUS.fetch(kind) * 2
+            { width: size, height: size }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "look"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # The outline of a note: a sheet with its top-right corner folded
+        # down and, on the side that faces the state it annotates, a tail
+        # to that state's border.
+        class NoteShape
+          # @param note [Layout::StateDiagram::Node] the note
+          # @param target [Layout::StateDiagram::Node, nil] the state it
+          #   annotates
+          def initialize(note, target)
+            @left = note.x
+            @top = note.y
+            @right = note.x + note.width
+            @bottom = note.y + note.height
+            @target = target
+          end
+
+          # @return [String] path data of the sheet and its tail
+          def outline
+            corners = [[@left, @top], [@left, @bottom], [@right, @bottom],
+                       [@right, @top + Look::FOLD],
+                       [@right - Look::FOLD, @top]]
+            index, tail = tail_at
+            corners.insert(index, *tail) if tail
+            closed(corners)
+          end
+
+          # @return [String] path data of the folded corner
+          def fold
+            edge = @right - Look::FOLD
+            closed([[edge, @top], [edge, @top + Look::FOLD],
+                    [@right, @top + Look::FOLD]])
+          end
+
+          private
+
+          def closed(points)
+            "M #{points.map { |point| point.join(' ') }.join(' L ')} Z"
+          end
+
+          def middle
+            (@top + @bottom) / 2.0
+          end
+
+          # @return [Array(Integer, Array), nil] where in the outline the
+          #   tail goes, and its three points
+          def tail_at
+            return unless @target
+
+            if @target.x >= @right
+              [3, tail(@right, @target.x)]
+            elsif @target.x + @target.width <= @left
+              [1, tail(@left, @target.x + @target.width).reverse]
+            end
+          end
+
+          # Drawn upward along the right side, downward along the left.
+          def tail(side, tip_x)
+            tip_y = middle.clamp(@target.y, @target.y + @target.height)
+            [[side, middle + Look::TAIL], [tip_x, tip_y],
+             [side, middle - Look::TAIL]]
+          end
+        end
+      end
+    end
+  end
+end