etassia 0.1.0

data/lib/etassia/layout/er_diagram_placement.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require_relative "er_diagram_entity_size"
+require_relative "er_diagram_layering"
+require_relative "er_diagram_ordering"
+require_relative "er_diagram_coordinates"
+require_relative "er_diagram_placement_node"
+
+module Etassia
+  module Layout
+    # Positions entities top to bottom the way mmdc's dagre does: relations
+    # point down the page, each rank is as tall as its tallest box, and a
+    # labelled relation holds a label-sized gap between its two ranks.
+    #
+    # Same contract as Grid.apply: x and y are written into the graph Hash
+    # in place, with the far corner of everything drawn under :extent.
+    # Self-loops take no part in the placement.
+    class ErDiagramPlacement
+      NODE_SPACING = 140
+      RANK_SPACING = 80
+      EDGE_SPACING = 20
+      MARGIN = 8
+      LABEL_FONT_SIZE = 14
+      LABEL_HEIGHT = 21
+
+      # @param graph [Hash] the graph to position in place
+      # @return [Hash] the same graph
+      def self.apply(graph)
+        new(graph).apply
+      end
+
+      def initialize(graph)
+        @graph = graph
+        @children = graph[:children] || []
+        @edges = graph[:edges] || []
+      end
+
+      def apply
+        return @graph if @children.empty?
+
+        build_nodes
+        layers = ErDiagramOrdering.call(@ranks, @chain)
+        centres = ErDiagramCoordinates.call(
+          layers, @chain, widths, dummies,
+          node: NODE_SPACING, edge: EDGE_SPACING
+        )
+        write(layers, centres)
+        @graph
+      end
+
+      private
+
+      def build_nodes
+        @nodes = @children.to_h { |child| [child[:id], entity_node(child)] }
+        @ranks, oriented = ErDiagramLayering.call(@nodes.keys, relation_pairs)
+        @chain = []
+        oriented.each_with_index { |pair, index| add_chain(pair, index) }
+      end
+
+      # A relation with an end that is not an entity takes no part, like a
+      # self-loop.
+      def relation_pairs
+        @edges.map do |edge|
+          pair = [edge[:sources]&.first, edge[:targets]&.first]
+          pair.all? { |id| @nodes.key?(id) } ? pair : [nil, nil]
+        end
+      end
+
+      # The relation becomes a chain of dummy nodes, one per rank crossed;
+      # the middle one is as big as the label.
+      def add_chain(pair, index)
+        return unless pair
+
+        from, to = pair
+        middle = (@ranks[from] + @ranks[to]) / 2
+        inner = ((@ranks[from] + 1)...@ranks[to]).map do |rank|
+          add_dummy("#{index}:#{rank}", rank, dummy_size(index, rank == middle))
+        end
+        @chain.concat([from, *inner, to].each_cons(2).to_a)
+      end
+
+      def add_dummy(id, rank, size)
+        @nodes[id] = dummy_node(id, size)
+        @ranks[id] = rank
+        id
+      end
+
+      def entity_node(child)
+        ErDiagramPlacementNode.new(
+          id: child[:id], width: child[:width], height: child[:height],
+          dummy: false
+        )
+      end
+
+      def dummy_node(id, size)
+        ErDiagramPlacementNode.new(id: id, dummy: true, **size)
+      end
+
+      def dummy_size(index, middle)
+        label = middle ? label_size(@edges[index]) : nil
+        label || { width: 0, height: 0 }
+      end
+
+      def label_size(edge)
+        label = (edge[:labels] || []).find { |item| !item[:position] }
+        text = label&.dig(:text)
+        return if text.to_s.empty?
+
+        width = ErDiagramEntitySize.text_width(text)
+        { width: width * LABEL_FONT_SIZE / ErDiagramEntitySize::FONT_SIZE,
+          height: LABEL_HEIGHT }
+      end
+
+      def widths
+        @nodes.transform_values(&:width)
+      end
+
+      def dummies
+        @nodes.transform_values(&:dummy?)
+      end
+
+      # The canvas reaches as far as the widest label or edge route, not
+      # only the entity boxes, so the extent covers every node in the layers.
+      def write(layers, centres)
+        left = layers.flatten.map { |id| left_side(id, centres) }.min
+        bottom = layers.reduce(MARGIN) do |top, layer|
+          place_layer(layer, centres, left, top)
+        end
+        @graph[:extent] = extent(layers, centres, left, bottom)
+      end
+
+      # @return [Numeric] where the next rank starts
+      def place_layer(layer, centres, left, top)
+        tallest = layer.map { |id| @nodes[id].height }.max || 0
+        place_entities(layer, centres, left, top + (tallest / 2.0))
+        top + (tallest + (RANK_SPACING / 2.0))
+      end
+
+      def place_entities(layer, centres, left, centre_y)
+        layer.reject { |id| @nodes[id].dummy? }.each do |id|
+          place(id, centres[id] - left + MARGIN, centre_y)
+        end
+      end
+
+      def left_side(id, centres)
+        centres[id] - (@nodes[id].width / 2.0)
+      end
+
+      def extent(layers, centres, left, bottom)
+        right = layers.flatten.map do |id|
+          centres[id] - left + MARGIN + (@nodes[id].width / 2.0)
+        end.max
+        [right, bottom - (RANK_SPACING / 2.0)]
+      end
+
+      def place(id, center_x, center_y)
+        child = @children.find { |item| item[:id] == id }
+        child[:x] = center_x - (child[:width] / 2.0)
+        child[:y] = center_y - (child[:height] / 2.0)
+      end
+    end
+  end
+end

data/lib/etassia/layout/er_diagram_placement_node.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # One box in the placement: an entity, or the stand-in for a point
+    # (or label) along a relationship that spans several ranks.
+    class ErDiagramPlacementNode
+      attr_reader :id, :width, :height
+
+      def initialize(id:, width:, height:, dummy:)
+        @id = id
+        @width = width
+        @height = height
+        @dummy = dummy
+      end
+
+      def dummy?
+        @dummy
+      end
+    end
+  end
+end

data/lib/etassia/layout/error.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../diagram/error"
+require_relative "../notation/mermaid/ir_adapters/error"
+
+module Etassia
+  module Layout
+    # Error diagram transformer for converting error models to renderable
+    # structure.
+    #
+    # Error diagrams have no complex layout requirements - they simply display
+    # an error message. This transformer prepares basic data for rendering.
+    #
+    # @example Transform an error diagram
+    #   layout = Error.new
+    #   scene = layout.call(error_diagram)
+    class Error < Base
+      class Box < Lutaml::Model::Serializable
+        attribute :x, :float
+        attribute :y, :float
+        attribute :width, :float
+        attribute :height, :float
+        attribute :corner_radius, :float
+      end
+
+      class Circle < Lutaml::Model::Serializable
+        attribute :x, :float
+        attribute :y, :float
+        attribute :radius, :float
+      end
+
+      class Label < Lutaml::Model::Serializable
+        attribute :text, :string
+        attribute :x, :float
+        attribute :y, :float
+        attribute :font_size, :float
+        attribute :text_anchor, :string
+        attribute :font_weight, :string
+      end
+
+      class Scene < Layout::Scene
+        attribute :id, :string
+        attribute :title, :string
+        attribute :view_box, :string
+        attribute :box, Box
+        attribute :icon, Circle
+        attribute :mark, Box
+        attribute :dot, Circle
+        attribute :label, Label
+        attribute :version_label, Label
+      end
+
+      def self.from_graph(graph, theme: nil)
+        layout = new
+        layout.theme = theme if theme
+        layout.send(:scene_from_graph, graph)
+      end
+
+      # Converts an error diagram to a simple data structure.
+      #
+      # Error diagrams don't need layout computation. This method validates
+      # the diagram and returns a structure for the renderer.
+      #
+      # @param diagram [Diagram::Error] the error diagram to transform
+      # @return [Hash] data structure for rendering
+      def build_graph(diagram)
+        data = ir_data(diagram)
+        {
+          id: data.id, title: data.label,
+          message: data.items.find { |item| item.role == "message" }&.label,
+          metadata: {
+            diagram_type: :error,
+          }
+        }
+      end
+
+      private
+
+      def scene(diagram)
+        scene_from_graph(build_graph(diagram))
+      end
+
+      def ir_data(diagram)
+        return diagram if diagram.is_a?(IR::Data)
+
+        Notation::Mermaid::IRAdapters::Error.call(diagram)
+      end
+
+      def scene_from_graph(graph)
+        Scene.new(
+          id: graph[:id] || "error", title: graph[:title],
+          width: 2412, height: 512, view_box: "0 0 2412 512",
+          box: error_box,
+          icon: Circle.new(x: 256, y: 256, radius: 256),
+          mark: error_mark,
+          dot: Circle.new(x: 256, y: 384, radius: 16),
+          label: error_label(graph),
+          version_label: version_label
+        )
+      end
+
+      def error_box
+        Box.new(x: 0, y: 0, width: 2412, height: 512, corner_radius: 8)
+      end
+
+      def error_mark
+        Box.new(x: 240, y: 128, width: 32, height: 192, corner_radius: 16)
+      end
+
+      def error_label(graph)
+        Label.new(
+          text: graph[:message] || "Error", x: 1440, y: 250,
+          font_size: font_size, text_anchor: "middle", font_weight: "bold"
+        )
+      end
+
+      def version_label
+        Label.new(
+          text: "mermaid version 11.12.0", x: 1250, y: 400,
+          font_size: 100, text_anchor: "middle", font_weight: "normal"
+        )
+      end
+
+      def font_size
+        value = theme.typography&.font_size_large
+        value&.positive? ? value : 16
+      rescue NoMethodError
+        16
+      end
+    end
+  end
+end

data/lib/etassia/layout/flowchart/brandes_koepf.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # dagre's horizontal placement: Brandes-Koepf over a layered graph.
+      # Each of the four alignments packs blocks of vertically aligned
+      # nodes; the result is the mean of the two middle candidates.
+      class BrandesKoepf
+        NODE_SEP = 50.0
+        EDGE_SEP = 20.0
+
+        # @param layers [Array<Array>] node ids, top layer first, in order
+        # @param widths [Hash] node id => width
+        # @param links [Array<Array>] [upper, lower] pairs on adjacent layers
+        # @param dummies [Array] ids that stand for an edge, not a box
+        # @return [Hash] node id => centre
+        def self.positions(layers, widths, links, dummies)
+          new(layers, widths, links, dummies).positions
+        end
+
+        def initialize(layers, widths, links, dummies)
+          @layers = layers
+          @widths = widths
+          @dummies = dummies
+          @up = index_links(links)
+          @down = index_links(links.map(&:reverse))
+        end
+
+        def positions
+          layouts = %i[up down].product(%i[left right]).map do |vert, horiz|
+            [horiz, layout(vert, horiz)]
+          end
+          balance(align_to_narrowest(layouts))
+        end
+
+        private
+
+        def index_links(links)
+          index = Hash.new { |hash, key| hash[key] = [] }
+          links.each_with_object(index) do |(upper, lower), result|
+            result[lower] << upper
+          end
+        end
+
+        def layout(vert, horiz)
+          layering = oriented_layers(vert, horiz)
+          roots = align_blocks(layering, neighbours(vert))
+          positions = compact(layering, roots)
+          horiz == :right ? mirror(positions) : positions
+        end
+
+        def oriented_layers(vert, horiz)
+          layering = vert == :up ? @layers : @layers.reverse
+          horiz == :right ? layering.map(&:reverse) : layering
+        end
+
+        def neighbours(vert)
+          vert == :up ? @up : @down
+        end
+
+        def mirror(positions)
+          positions.transform_values(&:-@)
+        end
+
+        def align_blocks(layering, neighbours)
+          root, pos = layer_indexes(layering)
+          align = root.dup
+          layering.each do |layer|
+            align_layer(layer, neighbours, root, align, pos)
+          end
+          root
+        end
+
+        def layer_indexes(layering)
+          root = {}
+          pos = {}
+          layering.each do |layer|
+            layer.each_with_index do |node, index|
+              root[node] = node
+              pos[node] = index
+            end
+          end
+          [root, pos]
+        end
+
+        def align_layer(layer, neighbours, root, align, pos)
+          taken = -1
+          layer.each do |node|
+            above = neighbours[node].sort_by { |other| pos[other] }
+            medians(above).each do |other|
+              next unless alignable?(node, other, taken, align, pos)
+
+              align_pair(node, other, root, align)
+              taken = pos[other]
+            end
+          end
+        end
+
+        def alignable?(node, other, taken, align, pos)
+          align[node] == node && taken < pos[other]
+        end
+
+        def align_pair(node, other, root, align)
+          align[other] = node
+          align[node] = root[node] = root[other]
+        end
+
+        def medians(sorted)
+          return [] if sorted.empty?
+
+          mid = (sorted.size - 1) / 2.0
+          sorted.values_at(mid.floor, mid.ceil).uniq
+        end
+
+        def compact(layering, root)
+          lefts, rights = constraints(layering, root)
+          settled = pack_right(root.values.uniq, rights, pack_left(lefts, root))
+          root.transform_values { |block| settled[block] }
+        end
+
+        def constraints(layering, root)
+          lefts = block_graph
+          rights = block_graph
+          layering.each do |layer|
+            layer.each_cons(2) do |near, far|
+              constrain(lefts, rights, root, near, far)
+            end
+          end
+          [lefts, rights]
+        end
+
+        def block_graph
+          Hash.new { |hash, key| hash[key] = {} }
+        end
+
+        def constrain(lefts, rights, root, near, far)
+          near_block = root[near]
+          far_block = root[far]
+          kept = lefts[far_block].fetch(near_block, 0)
+          gap = [separation(near, far), kept].max
+          connect(lefts, far_block, near_block, gap)
+          connect(rights, near_block, far_block, gap)
+        end
+
+        def connect(graph, from, to, gap)
+          graph[from][to] = gap
+        end
+
+        def pack_left(lefts, root)
+          memo = {}
+          visit = lambda do |block|
+            memo[block] ||= lefts[block].map do |near, gap|
+              visit.call(near) + gap
+            end.push(0).max
+          end
+          root.values.uniq.each { |block| visit.call(block) }
+          memo
+        end
+
+        def pack_right(blocks, rights, packed)
+          memo = {}
+          visit = lambda do |block|
+            memo[block] ||= begin
+              limit = rights[block].map { |far, gap| visit.call(far) - gap }.min
+              limit ? [packed[block], limit].max : packed[block]
+            end
+          end
+          blocks.each { |block| visit.call(block) }
+          memo
+        end
+
+        def separation(near, far)
+          half = ->(node) { @widths[node] / 2.0 }
+          reach = ->(node) { @dummies.include?(node) ? EDGE_SEP : NODE_SEP }
+          half.(near) + half.(far) + ((reach.(near) + reach.(far)) / 2.0)
+        end
+
+        def align_to_narrowest(layouts)
+          narrowest = layouts.min_by { |_, xs| extent(xs) }.last
+          low, high = narrowest.values.minmax
+          layouts.map do |horiz, xs|
+            align_layout(horiz, xs, low, high)
+          end
+        end
+
+        def align_layout(horiz, positions, low, high)
+          edge = horiz == :left ? positions.values.min : positions.values.max
+          target = horiz == :left ? low : high
+          delta = target - edge
+          positions.transform_values { |position| position + delta }
+        end
+
+        def extent(positions)
+          positions.map { |node, x| x + (@widths[node] / 2.0) }.max -
+            positions.map { |node, x| x - (@widths[node] / 2.0) }.min
+        end
+
+        def balance(candidates)
+          candidates.first.keys.to_h do |node|
+            middle = candidates.map { |xs| xs[node] }.sort[1, 2]
+            [node, middle.sum / 2.0]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/etassia/layout/flowchart/cluster_reach.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    class Flowchart < Base
+      # Stretches a subgraph across the boxes that have an edge into it.
+      #
+      # dagre lays a subgraph out together with the graph around it. An edge
+      # from a box beside the subgraph passes through the ranks the subgraph
+      # spans, and the subgraph's borders keep clear of it, so the subgraph
+      # grows along the rank to cover where the edge comes from. Works on a
+      # level whose boxes are already placed.
+      class ClusterReach
+        # Distance from the centre of a box with an edge into the subgraph to
+        # the subgraph's border on that side, as dagre leaves it.
+        REACH = 46.0
+
+        # @param boxes [Array<Hash>] the placed boxes of one level
+        # @param level_edges [Array] [edge, source box id, target box id]
+        #   triples laid out at that level
+        # @param sideways [Boolean] whether ranks run left to right
+        def self.apply(boxes, level_edges, sideways:)
+          new(boxes, sideways).apply(level_edges)
+        end
+
+        def initialize(boxes, sideways)
+          @boxes = boxes
+          @position, @size = sideways ? %i[y height] : %i[x width]
+          @by_id = {}
+          boxes.each { |box| @by_id[box[:id]] ||= box }
+        end
+
+        def apply(level_edges)
+          wanted = Hash.new { |hash, key| hash[key] = [] }
+          level_edges.each do |(_edge, from, to)|
+            reach(wanted, @by_id[from], @by_id[to])
+            reach(wanted, @by_id[to], @by_id[from])
+          end
+          wanted.each { |cluster, centres| stretch(cluster, centres) }
+        end
+
+        private
+
+        def reach(wanted, cluster, other)
+          return unless cluster && other && !cluster.equal?(other)
+          return unless cluster.dig(:metadata, :cluster) == true
+
+          wanted[cluster] << (other[@position] + (other[@size] / 2.0))
+        end
+
+        def stretch(cluster, centres)
+          low = [cluster[@position], centres.min - REACH].min
+          high = [cluster[@position] + cluster[@size], centres.max + REACH].max
+          before = cluster[@position]
+          return if low == before && high == before + cluster[@size]
+
+          resize(cluster, low, high)
+        end
+
+        # The contents stay where they are on the page.
+        def resize(cluster, low, high)
+          grown = cluster[@position] - low
+          cluster[@position] = low
+          cluster[@size] = high - low
+          (cluster[:children] || []).each { |child| child[@position] += grown }
+        end
+      end
+    end
+  end
+end