etassia 0.1.0

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

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "route_geometry"
+require_relative "label_clearance"
+require_relative "route_detour"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Writes each transition of a placed state graph as absolute
+        # `:sections` plus the point its label sits at.
+        #
+        # A transition between two boxes of one container keeps the route ELK
+        # gave it. Every other one (a loop, one that crosses a container's
+        # border, one beside a note, one ELK dropped to break a cycle) is a
+        # straight line between the two states' borders. Transitions between
+        # the same two states are spread apart so none hides another.
+        class Routes
+          include RouteGeometry
+          include LabelClearance
+          include RouteDetour
+
+          # @return [Array(String, String), nil] the two members of a
+          #   container the edge joins, nil when it does not join two of them
+          def self.level_pair(edge, parent, ids)
+            source = member_of(edge[:sources].first, parent, ids)
+            target = member_of(edge[:targets].first, parent, ids)
+            [source, target] if source && target && source != target
+          end
+
+          def self.member_of(id, parent, ids)
+            id = parent[id] until id.nil? || ids.include?(id)
+            id
+          end
+
+          def initialize(graph, nodes, parent, levels, label_reach)
+            @graph = graph
+            @nodes = nodes
+            @parent = parent
+            @levels = levels
+            @label_reach = label_reach
+            @boxes = {}
+            @degree = degrees(graph[:edges])
+            @placed = []
+            @detoured = []
+            @lanes = Hash.new(0)
+          end
+
+          def write
+            measure(@graph[:children], 0.0, 0.0)
+            @slots = label_slots
+            routed = @graph[:edges].map { |edge| [edge, polyline(edge)] }
+            spread(routed).each do |edge, points, slot|
+              record(edge, points, slot)
+            end
+          end
+
+          private
+
+          def record(edge, points, slot)
+            slotted = @slots[edge]
+            points = through(points, slotted) if slotted
+            edge[:sections] = [section(points)]
+            label = edge[:labels]&.first
+            spot = label_point(label_route(edge, points), label, slot)
+            edge[:label_at] = stood(slotted, label) if slotted
+            edge[:label_at] ||= settled(spot, points, label)
+          end
+
+          def stood(slotted, label)
+            slotted.slice(:x, :y).tap { |at| @placed << rect_at(at, label) }
+          end
+
+          # A line whose label has a slot of its own bends through the left
+          # of that slot, as graphviz routes it through its label node.
+          def through(points, slotted)
+            [points.first, [slotted[:via], slotted[:y]], points.last]
+          end
+
+          # The labels that share a rank inside a container stand in the slots
+          # {LabelReach} gives them, which also size that container.
+          def label_slots
+            containers = @boxes.values.select { |box| box.node[:children] }
+            containers.flat_map { |box| container_slots(box) }
+              .each_with_object({}.compare_by_identity) do |(edge, at), found|
+                found[edge] = at
+              end
+          end
+
+          def container_slots(box)
+            @label_reach.slots(box.node[:children]).map do |edge, at|
+              [edge, { x: box.x + at[:x], y: box.y + at[:y],
+                       via: box.x + at[:via] }]
+            end
+          end
+
+          def measure(children, left, top)
+            children.each do |node|
+              box = Box.new(left + node[:x], top + node[:y],
+                            node[:width], node[:height], node)
+              @boxes[node[:id]] = box
+              measure(node[:children] || [], box.x, box.y)
+            end
+          end
+
+          def polyline(edge)
+            source = edge[:sources].first
+            target = edge[:targets].first
+            return loop_points(@boxes.fetch(source)) if source == target
+
+            route = elk_route(edge, source, target) ||
+              straight(source, target)
+            detoured = around_boxes(edge, route)
+            @detoured << edge.object_id if detoured != route
+            detoured
+          end
+
+          # A route bent round a box carries its label along the route
+          # itself; a straight one may slide its label along the chord.
+          def label_route(edge, points)
+            return points if @detoured.include?(edge.object_id)
+
+            clear_of_containers(edge, points)
+          end
+
+          def elk_route(edge, source, target)
+            owner, level = @levels.find { |_, found| placed_edge(found, edge) }
+            placed = level && placed_edge(level, edge)
+            return unless placed && direct?(placed, source, target)
+
+            origin = owner ? @boxes.fetch(owner) : Box.new(0.0, 0.0, 0, 0, nil)
+            shifted(placed[:sections].first, origin, level[:shift])
+          end
+
+          def placed_edge(level, edge)
+            level[:elk]&.fetch(:edges)&.find do |found|
+              found[:id] == edge.object_id.to_s && found[:sections]&.any?
+            end
+          end
+
+          # The ELK route joins the two boxes of the container; it is the
+          # edge's own route only when those are the two states themselves
+          # and neither carries a note.
+          def direct?(placed, source, target)
+            placed[:sources] == [source] && placed[:targets] == [target] &&
+              !noted?(source) && !noted?(target)
+          end
+
+          def noted?(id)
+            @boxes.each_value.any? do |box|
+              box.node.dig(:metadata, :note_target) == id
+            end
+          end
+
+          def straight(source, target)
+            from = @boxes.fetch(source)
+            to = @boxes.fetch(target)
+            [border(from, centre(to)), border(to, centre(from))]
+          end
+
+          def spread(routed)
+            groups = routed.group_by { |edge, _| pair_key(edge) }
+            groups.flat_map { |key, group| spread_group(key, group) }
+          end
+
+          def spread_group(key, group)
+            group.each_with_index.map do |(edge, points), index|
+              slot = Slot.new(index, group.size, 0.0)
+              slot.offset = slot.lane * SPREAD
+              [edge, move(points, key, slot.offset), slot]
+            end
+          end
+
+          def pair_key(edge)
+            [edge[:sources].first, edge[:targets].first].sort
+          end
+
+          # Parts a route from the others of its pair, across the line
+          # between the two states taken in one fixed order so a pair's two
+          # directions part ways. A straight route bows through one bend
+          # point; a longer one moves over.
+          def move(points, key, offset)
+            return points if offset.zero? || key.first == key.last
+
+            from = centre(@boxes.fetch(key.first))
+            to = centre(@boxes.fetch(key.last))
+            return bowed(points, from, to, offset) if points.size == 2
+
+            sideways(points, from, to, offset)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # States of one container placed on one rank, left to right, each
+        # with its note. A note and its target make one slot: the note at its
+        # side and as much room on the other, so the targets of a column
+        # stay in line however their notes fall.
+        class Row
+          GAP = 50.0
+          NOTE_GAP = 30.0
+          private_constant :GAP, :NOTE_GAP
+
+          attr_reader :id, :nodes
+
+          # @param nodes [Array<Hash>] the states, in order
+          # @param notes [Hash{String=>Hash}] the note of a state by its id
+          def initialize(nodes, notes)
+            @nodes = nodes
+            @notes = notes
+            @id = nodes.size > 1 ? "row:#{nodes.first[:id]}" : nodes.first[:id]
+          end
+
+          def width
+            @nodes.sum { |node| slot_width(node) } + (GAP * (@nodes.size - 1))
+          end
+
+          def height
+            @nodes.map { |node| slot_height(node) }.max
+          end
+
+          # @return [Float] the left of the row's box
+          def left
+            first = @nodes.first
+            note = @notes[first[:id]]
+            first[:x] - (note ? note[:width] + NOTE_GAP : 0)
+          end
+
+          # Moves each state and note `shift` to the right.
+          def slide(shift)
+            @nodes.each do |node|
+              node[:x] += shift
+              @notes[node[:id]]&.then { |note| note[:x] += shift }
+            end
+          end
+
+          # Writes the position of each state and note, the row's box at
+          # `left`, `top`.
+          def place(left, top)
+            @nodes.each do |node|
+              place_slot(node, left, top + ((height - slot_height(node)) / 2))
+              left += slot_width(node) + GAP
+            end
+          end
+
+          private
+
+          def slot_width(node)
+            note = @notes[node[:id]]
+            return node[:width] unless note
+
+            node[:width] + (2 * (note[:width] + NOTE_GAP))
+          end
+
+          def slot_height(node)
+            [node[:height], @notes[node[:id]]&.fetch(:height).to_f].max
+          end
+
+          def place_slot(node, left, top)
+            note = @notes[node[:id]]
+            node[:y] = top + ((slot_height(node) - node[:height]) / 2)
+            node[:x] = note ? left + note[:width] + NOTE_GAP : left
+            place_note(node, note, left, top) if note
+          end
+
+          def place_note(node, note, left, top)
+            beyond = node[:x] + node[:width] + NOTE_GAP
+            leftward = note.dig(:metadata, :note_position) == "left"
+            note[:x] = leftward ? left : beyond
+            note[:y] = top + ((slot_height(node) - note[:height]) / 2)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Chains the states of a container that PlantUML draws on one rank:
+        # those joined by a flat (single-dash) transition, in the order the
+        # transitions run.
+        class Rows
+          # @param flat [Array<Array(String, String)>] the flat transitions,
+          #   as source and target ids
+          def initialize(flat)
+            @flat = flat
+          end
+
+          # @param ids [Array<String>] the states of one container
+          # @return [Array<Array<String>>] every state in exactly one chain
+          def chains(ids)
+            follower = followers(ids)
+            chained = (ids - follower.values).map { |id| chain(id, follower) }
+            chained + (ids - chained.flatten).zip
+          end
+
+          private
+
+          def followers(ids)
+            @flat.each_with_object({}) do |(from, to), found|
+              next unless joins?(ids, from, to) && !found.key?(from)
+
+              found[from] = to unless found.value?(to)
+            end
+          end
+
+          def joins?(ids, from, to)
+            from != to && ids.include?(from) && ids.include?(to)
+          end
+
+          def chain(id, follower)
+            row = [id]
+            while (onward = follower[row.last]) && !row.include?(onward)
+              row << onward
+            end
+            row
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module State
+        # Lowers a state inside a top-level composite to the rank below
+        # another composite it follows, and stretches its composite to
+        # hold it. PlantUML ranks every state across all containers at once,
+        # so a transition from one composite's bottom to a state of another
+        # puts that state a rank under the first composite, however short
+        # its own container would be.
+        class Stretch
+          # The distance from a composite's bottom to the state a transition
+          # out of it leads to: one rank and the label that rank carries.
+          RANK_GAP = 77.0
+          private_constant :RANK_GAP
+
+          # @param edges [Array<Hash>] the transitions, ELK-shaped
+          # @param nodes [Hash{String=>Hash}] every state by id
+          # @param parent [Hash{String=>String}] the container of each state
+          # @param ranking [Ranking]
+          def initialize(edges, nodes, parent, ranking)
+            @edges = edges
+            @nodes = nodes
+            @parent = parent
+            @ranking = ranking
+          end
+
+          # @param top [Array<Hash>] the placed top-level states
+          # @return [Array<Hash>] the states that moved
+          def apply(top)
+            composites = top.select { |node| Array(node[:children]).any? }
+            ids = composites.map { |node| node[:id] }
+            @edges.flat_map do |edge|
+              lower(edge, @nodes[edge[:sources].first], ids)
+            end
+          end
+
+          private
+
+          def lower(edge, source, ids)
+            target = @nodes[edge[:targets].first]
+            holder = @nodes[@parent[target[:id]]]
+            return [] unless follows?(source, target, holder, ids)
+
+            drop = floor(source) - holder[:y] - target[:y]
+            drop.positive? ? sink(holder, target, drop) : []
+          end
+
+          def floor(source)
+            source[:y] + source[:height] + RANK_GAP
+          end
+
+          def follows?(source, target, holder, ids)
+            holder && !holder.equal?(source) &&
+              ids.include?(source[:id]) && ids.include?(holder[:id]) &&
+              @ranking.below?(target[:id], source[:id])
+          end
+
+          def sink(holder, target, drop)
+            moved = holder[:children].select { |node| node[:y] >= target[:y] }
+            moved.each { |node| node[:y] += drop }
+            holder[:height] += drop
+            moved
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "../../parser/state_diagram"
+require_relative "../mermaid/ir_adapters/state_diagram"
+require_relative "style"
+require_relative "state/reader"
+require_relative "state/layout"
+require_relative "state/renderer"
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The PlantUML state diagram. The front end reads PlantUML's source into
+      # the state model Etassia already lays out and draws, so the picture is
+      # the one a Mermaid state diagram gets. Dispatched to from
+      # {PlantUML.parse}.
+      module State
+        extend self
+
+        # Lines only a state diagram has: a `state` declaration or a
+        # transition from or to the initial/final marker.
+        MARKER = /\A(?:state\s+(?!.*(?:-+>|<-+))\S|
+                   \[\*\][ \t]*-+(?:[a-z]+-+)?>|<-+[ \t]*\[\*\]|
+                   \S+[ \t]+-+(?:[a-z]+-+)?>[ \t]*\[\*\])/xi
+        # Lines another family owns; a source with one is never claimed.
+        OTHER = /\A(?:class|abstract|interface|enum|participant|actor|
+                 usecase|component|start|partition|fork)\b/xi
+        private_constant :MARKER, :OTHER
+
+        # @return [Boolean] whether the source reads as a state diagram
+        def state?(source)
+          lines = Reader.lines_of(source).map(&:first)
+          lines.none? { |line| OTHER.match?(line) } &&
+            lines.any? { |line| MARKER.match?(line) }
+        end
+
+        # @return [Notation::Parsed]
+        def parse(source)
+          reader = Reader.new
+          model = reader.parse(source)
+          Notation::Parsed.new(
+            type: :state_diagram,
+            diagram: Etassia::Notation::Mermaid::IRAdapters::StateDiagram.call(model),
+            transform: Layout.with_flat(reader.flat),
+            renderer: Binding.new(Style::Reader.read(source),
+                                  Reader.scale_of(source)),
+          )
+        end
+
+        # The renderer class of one diagram: the engine builds a renderer
+        # with `new(theme:)` only, so the diagram's style and `scale` travel
+        # here.
+        Binding = Struct.new(:sheet, :scale) do
+          def new(theme: nil)
+            Renderer.new(theme: theme, style: sheet, scale: scale)
+          end
+        end
+        private_constant :Binding
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/stereotype_head.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      # The header of a lone class carrying one `<<stereotype>>`, as
+      # PlantUML 1.2026.6 draws it: the circle at the left, the stereotype
+      # and the name stacked and centred on each other to its right. Numbers
+      # are offsets from the box's top left corner, measured against the
+      # PlantUML jar on stereotypes of three widths and names of three.
+      module StereotypeHead
+        extend self
+
+        STEREOTYPE_BASELINE = 16.6016
+        NAME_BASELINE = 32.668
+        CIRCLE_X = 15.0
+        CIRCLE_Y = 20.3105
+        BLOCK_LEFT = 27.0
+        STEREOTYPE_SIDE = 28.0
+        NAME_SIDE = 32.0
+        NAME_LEFT = 29.0
+        private_constant :STEREOTYPE_BASELINE, :NAME_BASELINE, :CIRCLE_X,
+                         :CIRCLE_Y, :BLOCK_LEFT, :STEREOTYPE_SIDE,
+                         :NAME_SIDE, :NAME_LEFT
+
+        # @param klass [Klass]
+        # @param circle [Boolean] whether the circle is drawn
+        # @return [Boolean] whether the class gets this header
+        def applies?(klass, circle:)
+          circle && klass.kind == :class && klass.stereotypes.one? &&
+            ClassName.lines(klass.name).one?
+        end
+
+        # @return [Float] the width the header alone asks of the box
+        def width(stereotype_width, name_width)
+          [stereotype_width + STEREOTYPE_SIDE, name_width + NAME_SIDE].max
+        end
+
+        # @return [Float] x of the centre line the two rows share, from the
+        #   box's left edge
+        def centre(stereotype_width, name_width)
+          left = name_width + 4.0 > stereotype_width ? NAME_LEFT : BLOCK_LEFT
+          left + ([stereotype_width, name_width].max / 2.0)
+        end
+
+        # @return [Array<Float>] baselines of the stereotype and the name
+        def baselines
+          [STEREOTYPE_BASELINE, NAME_BASELINE]
+        end
+
+        # @return [Array<Float>] the circle's centre
+        def circle_centre
+          [CIRCLE_X, CIRCLE_Y]
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style/bound.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # A renderer class tied to one diagram's {Sheet}. The engine builds
+        # a renderer with `new(theme:)` only, so the sheet travels in this
+        # wrapper, which stands where the renderer class stood.
+        class Bound
+          # @return [Class, Bound] the renderer itself when the source set
+          #   nothing and the renderer's own defaults already apply
+          def self.wrap(renderer, sheet)
+            sheet.styled? ? new(renderer, sheet) : renderer
+          end
+
+          # @param renderer [Class] a renderer taking `style:` as well as
+          #   `theme:`
+          # @param sheet [Sheet] the diagram's style
+          def initialize(renderer, sheet)
+            @renderer = renderer
+            @sheet = sheet
+            freeze
+          end
+
+          # @return [Object] a renderer that draws with the sheet
+          def new(theme: nil)
+            @renderer.new(theme: theme, style: @sheet)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/notation/plantuml/style/colour.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "colour_names"
+
+module Etassia
+  module Notation
+    module PlantUML
+      module Style
+        # Reads a PlantUML colour (`#red`, `LightYellow`, `#F80`, `#a1b2c3`,
+        # `#white|red` for a gradient) as the `#RRGGBB` PlantUML writes into
+        # its SVG, or "none" for `transparent`.
+        module Colour
+          extend self
+
+          HEX = /\A\h{3}(?:\h{3})?\z/
+          GRADIENT = /[|\\\/-]/
+          private_constant :HEX, :GRADIENT
+
+          # @param text [String] the colour, with or without its `#`
+          # @return [String, nil] the hex colour, "none", or nil when the
+          #   text names no colour; a gradient reads as its first colour
+          def resolve(text)
+            word = text.to_s.strip.delete_prefix("#").split(GRADIENT).first
+            return if word.nil? || word.empty?
+            return "none" if word.casecmp?("transparent")
+            return expand(word) if HEX.match?(word)
+
+            ColourNames::TABLE[word.downcase]
+          end
+
+          private
+
+          def expand(digits)
+            digits = digits.gsub(/\h/) { |digit| digit * 2 } if digits.size == 3
+            "##{digits.upcase}"
+          end
+        end
+      end
+    end
+  end
+end