etassia 0.1.0

data/lib/etassia/layout/sequence/message_rows.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/sequence_text"
+require_relative "creations"
+require_relative "geometry"
+require_relative "text_wrap"
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # The text lines of every message, and how much taller each row grows
+      # for them. A message wraps when mermaid wraps it, at the wider of
+      # the room between its two actors and one actor box.
+      class MessageRows
+        # mmdc's measured height of one 16px line, per pixel of font size.
+        LINE_ADVANCE_RATIO = 1.09
+        ACTIVATION_EDGE = 2
+        HEAD_INSET = 3
+        PADDING = 20
+        SELF_DROP = 30
+        # A message with no text lacks the 34px its first line brings.
+        EMPTY_DROP = 34
+        MIN_LIMIT = Geometry::ACTOR_WIDTH
+        FLAT_HEADS = %w[none stick_top stick_bottom].freeze
+        TURNED_HEADS = %w[half_top half_bottom].freeze
+
+        # @param edges [Array<Hash>] messages: sources, targets, metadata
+        # @param positions [Hash] participant id to its center_x
+        # @param font_size [Numeric] message text size
+        # @param wrap [Boolean] the diagram's wrap setting
+        # @param closers [Array<Integer>] messages a frame ends right after
+        # @param creators [Array<Integer>] messages that create a participant
+        def initialize(edges, positions, font_size:, wrap: false, **options)
+          check_options!(options)
+          @edges = edges || []
+          @positions = positions
+          @font_size = font_size
+          @wrap = wrap
+          @closers = options.fetch(:closers) { [] }
+          @creators = options.fetch(:creators) { [] }
+        end
+
+        # @return [Boolean] the diagram's wrap setting
+        def wrap?
+          @wrap ? true : false
+        end
+
+        # @param index [Integer] message index
+        # @return [Array<String>] the lines mermaid draws, entities decoded
+        def lines(index)
+          return [] unless index
+
+          all_lines.fetch(index, [])
+        end
+
+        # @param index [Integer] message index
+        # @return [Numeric] height the message's extra lines add to its row
+        def extra(index)
+          return -EMPTY_DROP if textless?(index)
+
+          [lines(index).length - 1, 0].max * line_advance
+        end
+
+        # @return [Numeric] height added by the messages above `index`
+        def extra_before(index)
+          (0...index).sum { |at| extra(at) + self_drop(at) + creation_drop(at) }
+        end
+
+        # @return [Numeric] height added above and within `index`'s own row;
+        #   its self-loop pushes down the rows below it, not its own
+        def extra_through(index)
+          extra_before(index) + extra(index)
+        end
+
+        # @return [Numeric] height added by every message
+        def total_extra
+          extra_before(@edges.length)
+        end
+
+        # @return [Numeric] distance between two drawn lines of a message
+        def line_pitch
+          (@font_size * 1.2).round
+        end
+
+        private
+
+        def check_options!(options)
+          unknown = options.keys - %i[closers creators]
+          return if unknown.empty?
+
+          label = unknown.one? ? "keyword" : "keywords"
+          names = unknown.map(&:inspect).join(", ")
+          raise ArgumentError, "unknown #{label}: #{names}"
+        end
+
+        def textless?(index)
+          index && lines(index).all? { |line| line.strip.empty? }
+        end
+
+        # mmdc leaves 30 below a message to itself, for the loop, and 30
+        # more when a frame ends right after it.
+        def self_drop(index)
+          edge = @edges[index]
+          return 0 unless edge && edge[:sources].first == edge[:targets].first
+
+          @closers.include?(index) ? 2 * SELF_DROP : SELF_DROP
+        end
+
+        # mmdc leaves half a box below the message that creates one.
+        def creation_drop(index)
+          @creators.include?(index) ? Creations::DROP : 0
+        end
+
+        def line_advance
+          (@font_size * LINE_ADVANCE_RATIO).round
+        end
+
+        def all_lines
+          @all_lines ||= @edges.map { |edge| edge_lines(edge) }
+        end
+
+        def edge_lines(edge)
+          source = edge.dig(:metadata, :message_source).to_s
+          body = TextWrap.body(source)
+          raw = if TextWrap.wrapped?(source, @wrap)
+                  TextWrap.lines(body, limit(edge), @font_size)
+                else
+                  body.split(TextWrap::LINE_BREAK, -1)
+                end
+          raw.map { |line| Diagram::SequenceText.decode(line) }
+        end
+
+        def limit(edge)
+          [bounded_width(edge) + PADDING, MIN_LIMIT].max
+        end
+
+        def bounded_width(edge)
+          from, to = edge.values_at(:sources, :targets).map(&:first)
+          return 0 if from == to
+
+          centres = [from, to].map { |id| @positions.dig(id, :center_x) }
+          return 0 if centres.any?(&:nil?)
+
+          [(centres.first - centres.last).abs - trims(edge[:metadata]), 0].max
+        end
+
+        def trims(metadata)
+          style = (metadata || {})[:head_style]
+          side = (metadata || {})[:head_side]
+          trim = ACTIVATION_EDGE
+          trim += HEAD_INSET unless FLAT_HEADS.include?(style) || reverse?(side)
+          trim + (starts_inset?(style, side) ? HEAD_INSET : 0)
+        end
+
+        def reverse?(side)
+          side == "source"
+        end
+
+        def starts_inset?(style, side)
+          side == "both" || (reverse?(side) && TURNED_HEADS.include?(style))
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/sequence/note.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # A positioned note: its box and one label per text line.
+      class Note < Lutaml::Model::Serializable
+        attribute :x, :float
+        attribute :y, :float
+        attribute :width, :float
+        attribute :height, :float
+        attribute :lines, Label, collection: true, default: -> { [] }
+      end
+    end
+  end
+end

data/lib/etassia/layout/sequence/note_box.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/sequence_text"
+require_relative "geometry"
+require_relative "text_width"
+require_relative "text_wrap"
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # The box of one note and the text lines inside it. A note that
+      # mermaid wraps is sized first, then broken to fit its width; any
+      # other note is as wide as its widest line.
+      class NoteBox
+        LINE_BREAK = Diagram::SequenceText::LINE_BREAK
+        PADDING = 20
+        SIDE_GAP = 25
+        MIN_WIDTH = Geometry::ACTOR_WIDTH
+
+        # @param entry [Hash] text and position of the note
+        # @param centers [Array<Numeric>] center x of the actors it names
+        # @param size [Numeric] note text size
+        # @param wrap [Boolean] the diagram's wrap setting
+        # @param actor_width [Numeric] width of the first named actor
+        def initialize(entry, centers, size:, wrap: false,
+                       actor_width: MIN_WIDTH)
+          @entry = entry
+          @centers = centers
+          @size = size
+          @wrap = wrap
+          @actor_width = actor_width
+        end
+
+        # @return [Array<String>] the text lines, as the source writes them
+        def lines
+          @lines ||= if wrapped? && @centers.any?
+                       TextWrap.lines(body, width - PADDING, @size)
+                     else
+                       plain_lines
+                     end
+        end
+
+        # @return [Numeric] width of the box
+        def width
+          box.first
+        end
+
+        # @return [Numeric] x of the box's left edge
+        def left
+          box.last
+        end
+
+        private
+
+        def box
+          @box ||= case @entry[:position]
+                   when "left_of" then side_box(-1)
+                   when "right_of" then side_box(1)
+                   else over_box
+                   end
+        end
+
+        def wrapped?
+          return false if body.empty?
+
+          TextWrap.wrapped?(@entry[:text].to_s, @wrap)
+        end
+
+        def body
+          TextWrap.body(@entry[:text].to_s)
+        end
+
+        def plain_lines
+          body.split(LINE_BREAK, -1)
+        end
+
+        def side_box(side)
+          wide = side_width(side)
+          return [wide, @centers.first + SIDE_GAP] if side.positive?
+
+          [wide, @centers.first - SIDE_GAP - wide]
+        end
+
+        def side_width(side)
+          return unwrapped_width unless wrapped?
+
+          text = widest(TextWrap.lines(body, MIN_WIDTH, @size))
+          [text + (side.negative? ? PADDING : 0), MIN_WIDTH].max
+        end
+
+        def unwrapped_width
+          [widest(plain_lines) + PADDING, MIN_WIDTH].max
+        end
+
+        def over_box
+          span = @centers.max - @centers.min
+          width = over_width(span)
+          [width, ((@centers.min + @centers.max) / 2.0) - (width / 2)]
+        end
+
+        def over_width(span)
+          return span + (2 * SIDE_GAP) if wrapped? && span.positive?
+          return [@actor_width, MIN_WIDTH].max if wrapped?
+
+          [unwrapped_width, span + (2 * SIDE_GAP)].max
+        end
+
+        def widest(text_lines)
+          TextWidth.widest(text_lines, @size).to_f
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/sequence/note_placement.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/sequence_text"
+require_relative "geometry"
+require_relative "note_box"
+require_relative "text_width"
+require_relative "frame_placement"
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # Gives every note its own vertical slot between two message rows and
+      # reports how far that slot pushes the later rows down.
+      class NotePlacement
+        LINE_BREAK = Diagram::SequenceText::LINE_BREAK
+        FIRST_ROW = Geometry::FIRST_ROW
+        ROW_SPACING = Geometry::MESSAGE_PITCH
+        TOP_GAP = Geometry::NOTE_MARGIN
+        SLOT_GAP = Geometry::NOTE_MARGIN
+        PADDING = NoteBox::PADDING
+        NO_ROWS = Class.new do
+          def extra_before(_index) = 0
+
+          def wrap? = false
+        end.new.freeze
+        LINE_SPACING = 1.2
+
+        # @param graph [Etassia::IR::Graph] the sequence graph
+        # @return [Array<Hash>] text, position, participant_ids and
+        #   message_index per note, in source order
+        def self.entries(graph)
+          graph.nodes.select { |node| node.role == "note" }.map do |node|
+            entry_for(graph, node)
+          end
+        end
+
+        def self.entry_for(graph, node)
+          fields = fields_of(graph, node)
+          {
+            text: node.label.to_s, position: fields["note_position"],
+            message_index: fields["message_index"].to_i,
+            order: fields["order"].to_i,
+            participant_ids: reference_ids(graph, node)
+          }
+        end
+
+        def self.fields_of(graph, node)
+          details = graph.nodes.select { |item| item.parent_id == node.id }
+          details.to_h { |item| [item.role, item.label] }
+        end
+
+        def self.reference_ids(graph, node)
+          graph.edges.select do |edge|
+            edge.role == "note_reference" && edge.source_id == node.id
+          end.map(&:target_id)
+        end
+        private_class_method :entry_for, :fields_of, :reference_ids
+
+        # @param entries [Array<Hash>, nil] see {.entries}
+        # @param positions [Hash] participant id to its x/center_x
+        # @param font_size [Numeric] note text size
+        # @param frames [FramePlacement] frame room the notes sit between
+        # @param rows [MessageRows] height the messages' extra lines add
+        def initialize(entries, positions, font_size:,
+                       frames: FramePlacement.new, rows: NO_ROWS)
+          @entries = entries || []
+          @positions = positions
+          @font_size = font_size
+          @frames = frames
+          @rows = rows
+        end
+
+        # @return [Array<Note>] placed notes; ones naming no known
+        #   participant are left out
+        def notes
+          @notes ||= pairs.map(&:last)
+        end
+
+        # @param from [Integer] source order of the opening frame edge
+        # @param to [Integer] source order of the closing frame edge
+        # @return [Array<Numeric>, nil] left and right edge of the notes
+        #   written between the two, nil when there are none
+        def x_range(from, to)
+          inside = notes_between(from, to)
+          return if inside.empty?
+
+          [inside.map(&:x).min, inside.map { |n| n.x + n.width }.max]
+        end
+
+        # @return [Numeric] height all note slots add to the diagram
+        def total_height
+          slots.sum
+        end
+
+        # @param index [Integer] message index
+        # @return [Numeric] how far the note slots above it push it down
+        def shift_for(index)
+          @entries.each_index.sum do |at|
+            @entries[at][:message_index] <= index ? slots[at] : 0
+          end
+        end
+
+        # @param index [Integer] message index
+        # @param order [Integer] source order of a frame edge
+        # @return [Numeric] height of the note slots at `index` that
+        #   come before that edge in the source
+        def slots_before(index, order)
+          @entries.each_index.sum do |at|
+            entry = @entries[at]
+            at_index = entry[:message_index] == index
+            at_index && entry[:order] < order ? slots[at] : 0
+          end
+        end
+
+        # @return [Numeric] how far the left-most note reaches past the
+        #   left margin, 0 when none does
+        def overhang
+          left = notes.map(&:x).min
+          return 0 unless left && left < Geometry::DIAGRAM_MARGIN_X
+
+          Geometry::DIAGRAM_MARGIN_X - left
+        end
+
+        # @return [Numeric] the right-most x any note reaches
+        def right_edge
+          notes.map { |note| note.x + note.width }.max || 0
+        end
+
+        private
+
+        def notes_between(from, to)
+          inside = pairs.select do |entry, _note|
+            entry[:order] > from && entry[:order] < to
+          end
+          inside.map(&:last)
+        end
+
+        def pairs
+          @pairs ||= @entries.each_index.filter_map do |index|
+            note = build_note(index)
+            [@entries[index], note] if note
+          end
+        end
+
+        def build_note(index)
+          centers = centers_of(@entries[index])
+          return if centers.empty?
+
+          place(index, boxes.fetch(index))
+        end
+
+        def centers_of(entry)
+          entry[:participant_ids].filter_map do |id|
+            @positions.dig(id, :center_x)
+          end
+        end
+
+        def place(index, box)
+          top = top_of(index)
+          Note.new(x: box.left, y: top, width: box.width,
+                   height: height(box.lines),
+                   lines: line_labels(box.lines, box.left + (box.width / 2),
+                                      top))
+        end
+
+        def boxes
+          @boxes ||= @entries.map { |entry| box_for(entry) }
+        end
+
+        def box_for(entry)
+          NoteBox.new(entry, centers_of(entry), size: @font_size,
+                                                wrap: @rows.wrap?,
+                                                actor_width: actor_width(entry))
+        end
+
+        def actor_width(entry)
+          position = @positions[entry[:participant_ids].first] || {}
+          return NoteBox::MIN_WIDTH unless position[:x] && position[:center_x]
+
+          2 * (position[:center_x] - position[:x])
+        end
+
+        def line_height
+          (@font_size * LINE_SPACING).round
+        end
+
+        def height(lines)
+          (lines.length * line_height) + PADDING
+        end
+
+        def slots
+          @slots ||= boxes.map { |box| height(box.lines) + SLOT_GAP }
+        end
+
+        def top_of(index)
+          own = @entries[index][:message_index]
+          FIRST_ROW + (own * ROW_SPACING) + slots_above(index, own) +
+            TOP_GAP + @rows.extra_before(own) +
+            frame_offset(own, @entries[index][:order])
+        end
+
+        def slots_above(index, own)
+          @entries.first(index).each_index.sum do |at|
+            @entries[at][:message_index] <= own ? slots[at] : 0
+          end
+        end
+
+        def frame_offset(own, order)
+          lead = @frames.lead(own, order)
+          @frames.top_inset + @frames.row_shift(own - 1) + lead +
+            (lead.zero? ? 0 : TOP_GAP)
+        end
+
+        def line_labels(lines, center, top)
+          lines.each_with_index.map do |line, row|
+            Label.new(text: line, x: center, font_size: @font_size,
+                      y: top + (PADDING / 2) + (line_height * (row + 0.5)))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/sequence/text_width.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../../text_measurement"
+require_relative "../../text_measurement/times_advances"
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # Width of one line of sequence text as mmdc measures it.
+      #
+      # mermaid measures with no font family set, so the browser falls back
+      # to Times New Roman, whatever face the text is drawn in. A line is
+      # rounded to whole pixels. A character reference such as `#9829;` is
+      # measured in the placeholder form mermaid encodes it to, not as the
+      # character it draws as. Pair adjustments use Times New Roman's
+      # per-mille kerning units.
+      class TextWidth
+        TABLE = TextMeasurement::TimesAdvances::TABLE
+        KERNING = {
+          "Fi" => -20,
+          "Wo" => -80,
+        }.freeze
+        REFERENCE = /#(\w+);/
+        NUMERIC = /\A\+?\d+\z/
+        MARK = "fl°"
+        END_MARK = "¶ß"
+
+        # @param line [String] one line of text, as written in the source
+        # @param font_size [Numeric] text size in pixels
+        # @return [Integer] the line's width in whole pixels
+        def self.of(line, font_size)
+          characters = collapse(encode(line)).each_char.to_a
+          advances = characters.sum { |char| advance(char) }
+          advances += characters.each_cons(2).sum { |pair| kerning(pair) }
+          ((advances * font_size / 1000.0) + 0.5).floor
+        end
+
+        # @param lines [Array<String>] lines of text
+        # @return [Integer] the widest line, 0 when there are none
+        def self.widest(lines, font_size)
+          lines.map { |line| of(line, font_size) }.max || 0
+        end
+
+        def self.encode(line)
+          line.gsub(REFERENCE) do
+            name = Regexp.last_match(1)
+            "#{MARK}#{'°' if name.match?(NUMERIC)}#{name}#{END_MARK}"
+          end
+        end
+
+        # SVG text drops leading and trailing spaces and folds the rest.
+        def self.collapse(line)
+          line.gsub(/\s+/, " ").strip
+        end
+
+        def self.advance(char)
+          TABLE.fetch(char.ord) do
+            TextMeasurement.measure(char, font_size: 1000)[:width]
+          end
+        end
+
+        def self.kerning(pair)
+          KERNING.fetch(pair.join, 0)
+        end
+        private_class_method :encode, :collapse, :advance, :kerning
+      end
+    end
+  end
+end

data/lib/etassia/layout/sequence/text_wrap.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../diagram/sequence_text"
+require_relative "text_width"
+
+module Etassia
+  module Layout
+    class Sequence < Base
+      # Breaks sequence text into lines the way mermaid's wrapLabel does:
+      # words are packed greedily, and a word wider than the limit is cut
+      # into hyphenated pieces. Text that already holds a `<br>` is left
+      # alone. Widths come from TextWidth.
+      class TextWrap
+        LINE_BREAK = Diagram::SequenceText::LINE_BREAK
+        WRAP_ON = /\A\s*wrap:/i
+        WRAP_OFF = /\A\s*nowrap:/i
+        HYPHEN = "-"
+
+        # @param source [String] text as written, `wrap:` prefix included
+        # @param global [Boolean] the diagram's wrap setting
+        # @return [Boolean] whether mermaid wraps this text
+        def self.wrapped?(source, global)
+          return true if source.match?(WRAP_ON)
+
+          global && !source.match?(WRAP_OFF)
+        end
+
+        # @param source [String] text as written, `wrap:` prefix included
+        # @return [String] the text without its `wrap:`/`nowrap:` prefix
+        def self.body(source)
+          source.sub(Diagram::SequenceText::WRAP_PREFIX, "")
+        end
+
+        # @param text [String] text without its prefix
+        # @param limit [Numeric] widest a line may be before it breaks
+        # @param size [Numeric] font size in pixels
+        # @return [Array<String>] the lines, as the source writes them
+        def self.lines(text, limit, size)
+          return text.split(LINE_BREAK, -1) if text.match?(LINE_BREAK)
+
+          new(limit, size).lines(text)
+        end
+
+        def initialize(limit, size)
+          @limit = limit
+          @size = size
+        end
+
+        def lines(text)
+          done = []
+          line = ""
+          text.split(/ /).reject(&:empty?).each do |word|
+            line = place(word, line, done)
+          end
+          done.push(line).reject(&:empty?)
+        end
+
+        private
+
+        def place(word, line, done)
+          if width("#{word} ") > @limit
+            pieces, rest = break_word(word)
+            done.push(line, *pieces)
+            rest
+          elsif width(line) + width("#{word} ") >= @limit
+            done.push(line)
+            word
+          else
+            [line, word].reject(&:empty?).join(" ")
+          end
+        end
+
+        def break_word(word)
+          pieces = []
+          line = +""
+          chars = word.chars
+          chars.each_with_index do |char, index|
+            line << char
+            next if width(line) < @limit
+
+            pieces << (index == chars.length - 1 ? line : line + HYPHEN)
+            line = +""
+          end
+          [pieces, line]
+        end
+
+        def width(line)
+          TextWidth.of(line, @size)
+        end
+      end
+    end
+  end
+end