etassia 0.1.0

data/lib/etassia/layout/c4_boundary_metrics.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "c4_text"
+
+module Etassia
+  module Layout
+    # The heading of a C4 boundary: its name and "[type]" under it. The
+    # height is what mermaid's drawInsideBoundary reserves above the first
+    # box the boundary holds.
+    class C4BoundaryMetrics
+      LABEL_FONT_SIZE = 16
+      TYPE_FONT_SIZE = 14
+
+      attr_reader :label_offset, :type_offset, :height
+
+      # @param label [String] the boundary name
+      # @param type [String, nil] the type, drawn as "[type]"
+      def initialize(label:, type: nil, label_font_size: LABEL_FONT_SIZE,
+                     type_font_size: TYPE_FONT_SIZE)
+        @label_font_size = label_font_size
+        @type_font_size = type_font_size
+        @label_offset = 8
+        offset = @label_offset + C4Text.height(label.to_s, @label_font_size)
+        @type_offset = type.to_s.empty? ? nil : offset + 5
+        @height = @type_offset ? type_bottom(type) : offset
+      end
+
+      private
+
+      def type_bottom(type)
+        @type_offset + C4Text.height("[#{type}]", @type_font_size)
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_bounds.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # The running extent of one C4 boundary while its boxes are placed, a
+    # port of mermaid's Bounds. Boxes fill a row left to right and start a
+    # new row when the next one would pass the width limit or the row
+    # already holds the configured number.
+    class C4Bounds
+      MARGIN = 50
+
+      # A rectangle given by its four edges, grown to cover more.
+      class Extent
+        attr_accessor :startx, :stopx, :starty, :stopy
+
+        def reset(x_pos, y_pos)
+          @startx = @stopx = x_pos
+          @starty = @stopy = y_pos
+        end
+
+        def cover(left, top, right, bottom)
+          @startx = [@startx, left].min
+          @starty = [@starty, top].min
+          @stopx = [@stopx, right].max
+          @stopy = [@stopy, bottom].max
+        end
+      end
+
+      attr_reader :data, :width_limit
+
+      # @param width_limit [Numeric] the right edge a box may not reach
+      # @param per_row [Integer] boxes allowed in one row
+      def initialize(width_limit:, per_row:)
+        @width_limit = width_limit
+        @per_row = per_row
+        @data = Extent.new
+        @upcoming = Extent.new
+        @count = 0
+      end
+
+      # Restarts the extent at a point, as mermaid's setData does.
+      def start_at(x_pos, y_pos)
+        @data.reset(x_pos, y_pos)
+        @upcoming.reset(x_pos, y_pos)
+      end
+
+      # Gives a box node its :x and :y and grows the extent over it.
+      def insert(node)
+        @count += 1
+        left, top, right = position_for(node)
+        node[:x] = left
+        node[:y] = top
+        cover(left, top, right, top + node[:height])
+      end
+
+      def bump_last_margin
+        @data.stopx += MARGIN
+        @data.stopy += MARGIN
+      end
+
+      # Grows this extent to hold a finished child boundary and its margin.
+      def absorb(child)
+        @data.stopy = [child.data.stopy + MARGIN, @data.stopy].max
+        @data.stopx = [child.data.stopx + MARGIN, @data.stopx].max
+      end
+
+      private
+
+      def position_for(node)
+        left, top = origin
+        right = left + node[:width]
+        return next_line(node) if overflows?(left, right)
+
+        [left, top, right]
+      end
+
+      def origin
+        gap = @upcoming.startx == @upcoming.stopx ? MARGIN : MARGIN * 2
+        [@upcoming.stopx + gap, @upcoming.starty + (MARGIN * 2)]
+      end
+
+      def overflows?(left, right)
+        left >= @width_limit || right >= @width_limit || @count > @per_row
+      end
+
+      def next_line(node)
+        left = @upcoming.startx + MARGIN
+        top = @upcoming.stopy + (MARGIN * 2)
+        start_row(left, top, node)
+        [left, top, @upcoming.stopx]
+      end
+
+      def start_row(left, top, node)
+        @upcoming.stopx = left + node[:width]
+        @upcoming.starty = @upcoming.stopy
+        @upcoming.stopy = top + node[:height]
+        @count = 1
+      end
+
+      def cover(left, top, right, bottom)
+        @data.cover(left, top, right, bottom)
+        @upcoming.cover(left, top, right, bottom)
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_intersection.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Where a C4 relationship leaves one box and meets the other, a port of
+    # mermaid's getIntersectPoints. It aims at the other box's centre from
+    # the near corner of this one, so the result can differ from a true
+    # centre-to-centre crossing. Mermaid's choice, kept for parity.
+    class C4Intersection
+      # @param from [#x, #y, #width, #height] the box the line starts at
+      # @param to [#x, #y, #width, #height] the box the line ends at
+      # @return [Array<Array<Float>>] the start and end as [x, y] pairs
+      def self.points(from, to)
+        [leave(from, centre(to)), leave(to, centre(from))]
+      end
+
+      def self.centre(box)
+        [box.x + (box.width / 2.0), box.y + (box.height / 2.0)]
+      end
+
+      def self.leave(box, target)
+        axis_point(box, target) || diagonal_point(box, target) ||
+          centre(box)
+      end
+
+      def self.axis_point(box, target)
+        x_pos, y_pos = target
+        if box.y == y_pos
+          [horizontal_exit_x(box, x_pos), centre(box)[1]]
+        elsif box.x == x_pos
+          [centre(box)[0], vertical_exit_y(box, y_pos)]
+        end
+      end
+
+      def self.horizontal_exit_x(box, x_pos)
+        box.x < x_pos ? box.x + box.width : box.x
+      end
+
+      def self.vertical_exit_y(box, y_pos)
+        box.y < y_pos ? box.y + box.height : box.y
+      end
+
+      def self.diagonal_point(box, target)
+        dx, dy = offsets(box, target)
+        slope = dy.fdiv(dx)
+        if box.height.fdiv(box.width) >= slope
+          side_point(box, target, slope)
+        else
+          edge_point(box, target, dx.fdiv(dy))
+        end
+      end
+
+      def self.offsets(box, target)
+        [(box.x - target[0]).abs, (box.y - target[1]).abs]
+      end
+
+      def self.side_point(box, target, slope)
+        sign = box.y < target[1] ? 1 : -1
+        [side_x(box, target), centre(box)[1] + (sign * slope * box.width / 2.0)]
+      end
+
+      def self.side_x(box, target)
+        box.x > target[0] ? box.x : box.x + box.width
+      end
+
+      def self.edge_point(box, target, ratio)
+        sign = box.x > target[0] ? -1 : 1
+        [centre(box)[0] + (sign * ratio * box.height / 2.0),
+         vertical_exit_y(box, target[1])]
+      end
+
+      private_class_method :centre, :leave, :axis_point, :diagonal_point,
+                           :side_point, :edge_point, :horizontal_exit_x,
+                           :vertical_exit_y, :offsets, :side_x
+    end
+  end
+end

data/lib/etassia/layout/c4_placement.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "c4_bounds"
+require_relative "c4_boundary_metrics"
+
+module Etassia
+  module Layout
+    # Positions a C4 graph the way mermaid does, a port of its c4Renderer.
+    #
+    # Same contract as Grid.apply, except that every x and y written is
+    # absolute: a box inside a boundary is placed on the page, not inside
+    # its parent. The boundaries are visited depth first, each one placing
+    # its own boxes before the boundaries nested in it, and the canvas is
+    # what the page edge and the nested extents leave behind.
+    class C4Placement
+      # screen.availWidth in the headless Chrome mermaid-cli draws with.
+      # Read off the reference render of c4/c4-8ab0b1ef, where a 552 wide box
+      # wraps and a 216 wide one does not.
+      AVAILABLE_WIDTH = 800
+      MARGIN_X = 50
+      MARGIN_Y = 10
+      SHAPES_IN_ROW = 4
+      BOUNDARIES_IN_ROW = 2
+
+      # @param graph [Hash] the graph to position in place
+      # @return [Hash] the same graph, its metadata holding the :canvas
+      def self.apply(graph)
+        new.apply(graph)
+      end
+
+      def apply(graph)
+        @shapes_in_row = row_limit(graph, "Shape", SHAPES_IN_ROW)
+        @boundaries_in_row = row_limit(graph, "Boundary", BOUNDARIES_IN_ROW)
+        screen = start_screen
+        place_boundaries(screen, [global_boundary(graph)])
+        graph[:metadata] = graph[:metadata].to_h.merge(canvas: canvas)
+        graph
+      end
+
+      private
+
+      def row_limit(graph, name, default)
+        config = graph.dig(:metadata, :layout_config).to_s
+        value = config[/#{name}InRow\D*(\d+)/i, 1].to_i
+        value >= 1 ? value : default
+      end
+
+      def start_screen
+        @max_x = MARGIN_X
+        @max_y = MARGIN_Y
+        bounds_for(AVAILABLE_WIDTH).tap do |screen|
+          screen.start_at(MARGIN_X, MARGIN_Y)
+        end
+      end
+
+      def bounds_for(width_limit)
+        C4Bounds.new(width_limit: width_limit, per_row: @shapes_in_row)
+      end
+
+      # Mermaid keeps every box that is in no boundary in an implicit one.
+      def global_boundary(graph)
+        header = C4BoundaryMetrics.new(label: "global", type: "global")
+        { children: graph[:children], global: true, header: header.height }
+      end
+
+      def place_boundaries(parent, nodes)
+        across = [@boundaries_in_row, nodes.length].min
+        bounds = bounds_for(parent.width_limit.to_f / across)
+        nodes.each_with_index do |node, index|
+          start_bounds(parent, bounds, node, index)
+          place_contents(bounds, node)
+          frame(node, bounds)
+          parent.absorb(bounds)
+          grow_canvas(parent)
+        end
+      end
+
+      def start_bounds(parent, bounds, node, index)
+        if (index % @boundaries_in_row).zero?
+          x_pos = parent.data.startx + MARGIN_X
+          y_pos = parent.data.stopy + MARGIN_Y + header_height(node)
+        else
+          x_pos = beside_x(bounds)
+          y_pos = bounds.data.starty
+        end
+        bounds.start_at(x_pos, y_pos)
+      end
+
+      def beside_x(bounds)
+        data = bounds.data
+        data.stopx == data.startx ? data.startx : data.stopx + MARGIN_X
+      end
+
+      def header_height(node)
+        node[:header] || node.dig(:metadata, :header)
+      end
+
+      def place_contents(bounds, node)
+        children = node[:children].to_a
+        boxes, boundaries = children.partition { |child| box?(child) }
+        boxes.each { |box| bounds.insert(box) }
+        bounds.bump_last_margin unless boxes.empty?
+        place_boundaries(bounds, boundaries) unless boundaries.empty?
+      end
+
+      def box?(node)
+        !node.dig(:metadata, :boundary_type)
+      end
+
+      def frame(node, bounds)
+        return if node[:global]
+
+        data = bounds.data
+        node[:x] = data.startx
+        node[:y] = data.starty
+        node[:width] = data.stopx - data.startx
+        node[:height] = data.stopy - data.starty
+      end
+
+      def grow_canvas(parent)
+        @max_x = [@max_x, parent.data.stopx].max
+        @max_y = [@max_y, parent.data.stopy].max
+      end
+
+      def canvas
+        {
+          width: @max_x - MARGIN_X + (2 * MARGIN_X),
+          height: @max_y - MARGIN_Y + (2 * MARGIN_Y),
+          title_x: ((@max_x - MARGIN_X) / 2.0) - (4 * MARGIN_X),
+          title_y: MARGIN_Y * 2,
+        }
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_shape_metrics.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "c4_text"
+
+module Etassia
+  module Layout
+    # Size of a C4 person, system, container or component box and the
+    # offsets, from its top, of what is drawn inside it. A port of
+    # mermaid's drawC4ShapeArray: every offset below is the number that
+    # function adds, in the order it adds them.
+    class C4ShapeMetrics
+      PADDING = 20
+      MIN_WIDTH = 216
+      MIN_HEIGHT = 60
+      IMAGE_SIZE = 48
+      LABEL_FONT_SIZE = 16
+      BODY_FONT_SIZE = 14
+      STEREOTYPE_FONT_SIZE = 12
+
+      attr_reader :stereotype_offset, :image_offset, :label_offset,
+                  :technology_offset, :description_offset, :width, :height
+
+      # @param label [String] the element name
+      # @param technology [String, nil] drawn as "[technology]"
+      # @param description [String, nil] drawn below the name
+      # @param person [Boolean] reserves room for the person icon
+      def initialize(label:, technology: nil, description: nil, person: false,
+                     font_sizes: {})
+        @label = label.to_s
+        @technology = technology.to_s
+        @description = description.to_s
+        @person = person
+        @label_font_size = font_sizes.fetch(:label, LABEL_FONT_SIZE)
+        @body_font_size = font_sizes.fetch(:body, BODY_FONT_SIZE)
+        @stereotype_font_size =
+          font_sizes.fetch(:stereotype, STEREOTYPE_FONT_SIZE)
+        measure
+      end
+
+      private
+
+      def measure
+        @stereotype_offset = PADDING
+        offset = PADDING + @stereotype_font_size + 2 - 4
+        offset = place_image(offset)
+        offset = place_label(offset)
+        offset = place_technology(offset)
+        place_description(offset)
+      end
+
+      def place_image(offset)
+        return offset unless @person
+
+        @image_offset = offset
+        offset + IMAGE_SIZE
+      end
+
+      def place_label(offset)
+        @label_offset = offset + 8
+        @label_offset + C4Text.height(@label, @label_font_size)
+      end
+
+      def place_technology(offset)
+        return offset if @technology.empty?
+
+        @technology_offset = offset + 5
+        @technology_offset + C4Text.height(bracketed, @body_font_size)
+      end
+
+      def place_description(offset)
+        rect_width = C4Text.width(@label, @label_font_size)
+        rect_height = offset
+        unless @description.empty?
+          rect_width = [rect_width, description_width].max
+          rect_height = description_bottom(offset)
+        end
+        @width = [rect_width + PADDING, MIN_WIDTH].max
+        @height = [rect_height, MIN_HEIGHT].max
+      end
+
+      def description_bottom(offset)
+        @description_offset = offset + 20
+        text_height = C4Text.height(@description, @body_font_size)
+        bottom = @description_offset + text_height
+        bottom - (C4Text.lines(@description).length * 5)
+      end
+
+      def description_width
+        C4Text.width(@description, @body_font_size)
+      end
+
+      def bracketed
+        "[#{@technology}]"
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_shape_outline.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Path data for the C4 shapes mmdc draws outside the element box: a
+    # database cylinder and a queue pill. Each shape is a body path plus a
+    # rim path that closes the visible cap.
+    class C4ShapeOutline
+      CYLINDER_CAP = 10
+      PILL_CAP = 5
+
+      # @param shape [String, nil] "database", "queue" or anything else
+      # @param left [Numeric] left edge of the element box
+      # @param top [Numeric] top edge of the element box
+      # @param width [Numeric] element box width
+      # @param height [Numeric] element box height
+      def initialize(shape:, left:, top:, width:, height:)
+        @shape = shape
+        @left = Float(left)
+        @top = Float(top)
+        @width = Float(width)
+        @height = Float(height)
+      end
+
+      # @return [String, nil] body path data, nil for a plain box
+      def body
+        outline&.first
+      end
+
+      # @return [String, nil] rim path data, nil for a plain box
+      def rim
+        outline&.last
+      end
+
+      private
+
+      def outline
+        case @shape
+        when "database" then database
+        when "queue" then queue
+        end
+      end
+
+      def database
+        half = @width / 2
+        [
+          "M#{@left},#{@top}c0,-10 #{half},-10 #{half},-10c0,0 #{half},0 " \
+          "#{half},10l0,#{@height}c0,10 -#{half},10 -#{half},10" \
+          "c0,0 -#{half},0 -#{half},-10l0,-#{@height}",
+          "M#{@left},#{@top}c0,10 #{half},10 #{half},10c0,0 #{half},0 " \
+          "#{half},-10",
+        ]
+      end
+
+      def queue
+        half = @height / 2
+        [
+          "M#{@left},#{@top}l#{@width},0c5,0 5,#{half} 5,#{half}" \
+          "c0,0 0,#{half} -5,#{half}l-#{@width},0" \
+          "c-5,0 -5,-#{half} -5,-#{half}c0,0 0,-#{half} 5,-#{half}",
+          "M#{@left + @width},#{@top}c-5,0 -5,#{half} -5,#{half}" \
+          "c0,#{half} 5,#{half} 5,#{half}",
+        ]
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_stereotype.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # The "<<person>>" caption Mermaid draws above a C4 element's name.
+    class C4Stereotype
+      EXTERNAL_SUFFIX = "_Ext"
+
+      # @param element_type [String, nil] e.g. "Person_Ext", "SystemDb"
+      # @return [String, nil] e.g. "<<external_person>>"
+      def self.text(element_type)
+        return if element_type.nil? || element_type.empty?
+
+        prefix = element_type.end_with?(EXTERNAL_SUFFIX) ? "external_" : ""
+        base = element_type.delete_suffix(EXTERNAL_SUFFIX)
+        snake = base.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        "<<#{prefix}#{snake}>>"
+      end
+
+      # @param element_type [String, nil] e.g. "SystemDb_Ext", "ContainerQueue"
+      # @return [String, nil] "database", "queue", or nil for a plain box
+      def self.shape(element_type)
+        base = element_type.to_s.delete_suffix(EXTERNAL_SUFFIX)
+        return "database" if base.end_with?("Db")
+
+        "queue" if base.end_with?("Queue")
+      end
+    end
+  end
+end

data/lib/etassia/layout/c4_text.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "../text_measurement"
+
+module Etassia
+  module Layout
+    # Text sizes as mermaid's C4 renderer takes them from the browser: the
+    # widest line's width rounded to a whole pixel, and a fixed height per
+    # non-empty line. An empty line has no height, so an empty label adds
+    # nothing to a C4 element.
+    module C4Text
+      LINE_BREAK = %r{<br\s*/?>}i
+      LINE_HEIGHTS = { 12 => 14, 14 => 16, 16 => 17 }.freeze
+      LINE_HEIGHT_RATIO = 1.15
+      # Arial's kern table shifts this pair by -113/2048 em. Apply it before
+      # browser-style whole-pixel rounding so C4 boxes fit the drawn text.
+      KERNING_PER_MILLE = { "A " => -55 }.freeze
+
+      module_function
+
+      # @param text [String, nil] text that may hold <br/> breaks
+      # @return [Array<String>] the lines, never empty
+      def lines(text)
+        parts = text.to_s.split(LINE_BREAK, -1).map(&:strip)
+        parts.empty? ? [""] : parts
+      end
+
+      def width(text, font_size)
+        lines(text).map { |line| line_width(line, font_size) }.max
+      end
+
+      def height(text, font_size)
+        lines(text).sum { |line| line_height(line, font_size) }
+      end
+
+      def line_width(line, font_size)
+        measured = TextMeasurement.measure(line, font_size: font_size)[:width]
+        (measured + kerning(line, font_size)).round
+      end
+
+      def kerning(line, font_size)
+        pairs = line.each_char.each_cons(2)
+        adjustment = pairs.sum { |pair| KERNING_PER_MILLE.fetch(pair.join, 0) }
+        adjustment * font_size / 1000.0
+      end
+
+      def line_height(line, font_size)
+        return 0 if line.empty?
+
+        LINE_HEIGHTS.fetch(font_size) { (font_size * LINE_HEIGHT_RATIO).round }
+      end
+    end
+  end
+end