archsight 0.5.4 → 0.5.5

data/lib/archsight/diagram/layout/alignment.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Diagram
+    class Layout
+      # `align "top other"` (or `left`, `center`, `right`, `middle`, `bottom`; a bare id is `center`): once
+      # everything is placed, a node moves until that edge of it lines up with the same edge of the other node,
+      # which may sit in another container -- like the align buttons of a drawing editor. It only uses the
+      # free room its container already has, never growing one: where its container packs along that axis (a
+      # `layer` for left/right, a `stack` for up/down) it pushes its siblings along, keeping their order and
+      # gaps; elsewhere it moves within the container's inner box. It stops as close as it gets.
+      class Alignment
+        # Shifts below this are left alone (no visible change, no churn).
+        EPSILON = 0.5
+
+        AXES = { x: Axis::WIDTH, y: Axis::HEIGHT }.freeze
+
+        def initialize(graph, boxes, theme:)
+          @graph = graph
+          @boxes = boxes
+          @theme = theme
+        end
+
+        def apply
+          aligned = @graph.nodes_by_id.values.select(&:align)
+          return if aligned.empty?
+
+          # A second round settles a node aligned to a node that is aligned itself.
+          2.times do
+            aligned.each { |node| node.alignments.each { |axis, edge, id| align(node, AXES.fetch(axis), edge, id) } }
+          end
+        end
+
+        private
+
+        def align(node, axis, edge, target_id)
+          delta = wanted(axis, edge, @boxes[target_id]) - wanted(axis, edge, @boxes[node.id])
+          return if delta.abs < EPSILON
+
+          lo, hi = room(node, axis)
+          parent = node.parent
+          if parent && parent.main_axis == axis
+            sweep(parent.children.sort_by { |c| axis.position(@boxes[c.id]) }, node, axis, delta, lo, hi)
+          else
+            box = @boxes[node.id]
+            shift(node, axis, delta.clamp([lo - axis.leading_edge(box), 0.0].min, [hi - axis.trailing_edge(box), 0.0].max))
+          end
+          refit(parent, axis)
+        end
+
+        # The coordinate of `box` that `edge` lines up.
+        def wanted(axis, edge, box)
+          case edge
+          when "left", "top" then axis.leading_edge(box)
+          when "right", "bottom" then axis.trailing_edge(box)
+          else axis.position(box)
+          end
+        end
+
+        # The children of a container packed along `axis`, in order, with `node` wanting to move by `delta`: the
+        # others stay where they are unless they come closer to a neighbour than `min_gap`, then they are pushed
+        # along; everything stays inside `lo..hi`.
+        def sweep(children, node, axis, delta, lo, hi)
+          boxes = children.map { |c| @boxes[c.id] }
+          sizes = boxes.map { |b| axis.size(b) }
+          gaps = children.each_cons(2).map { |a, b| min_gap(a, b, axis) }
+          leads = boxes.each_with_index.map { |b, i| axis.leading_edge(b) + (children[i].equal?(node) ? delta : 0.0) }
+
+          push_on(leads, sizes, gaps)
+          leads[-1] = [leads[-1], hi - sizes[-1]].min
+          (leads.length - 2).downto(0) { |i| leads[i] = [leads[i], leads[i + 1] - gaps[i] - sizes[i]].min }
+          leads[0] = [leads[0], lo].max
+          push_on(leads, sizes, gaps)
+
+          children.each_with_index { |c, i| shift(c, axis, leads[i] - axis.leading_edge(boxes[i])) }
+        end
+
+        # How close two neighbours may come: the sibling gap plus half a port tab on each side that faces the
+        # other (see `RankArranger#port_overhangs`), never more than they are apart now.
+        def min_gap(a, b, axis)
+          current = [axis.leading_edge(@boxes[b.id]) - axis.trailing_edge(@boxes[a.id]), 0.0].max
+          trailing, leading = axis == Axis::HEIGHT ? %w[bottom top] : %w[right left]
+          [current, @theme.sibling_gap + tab_overhang(a, trailing) + tab_overhang(b, leading)].min
+        end
+
+        def tab_overhang(node, side)
+          return 0.0 unless node.leaf? && node.ports.any? { |p| p.side.nil? || p.side == side }
+
+          PortMetrics.new(@theme).height / 2.0
+        end
+
+        # Each leading edge at least its gap past the box before it.
+        def push_on(leads, sizes, gaps)
+          (1...leads.length).each { |i| leads[i] = [leads[i], leads[i - 1] + sizes[i - 1] + gaps[i - 1]].max }
+        end
+
+        # The room (lo, hi) a node may move in along `axis`: its container's inner box. An anonymous container
+        # packing along that axis is only as long as its children, so its room is that of its own container
+        # (one packing across it is as long as the line it sits in). Top-level nodes may use the whole drawing.
+        def room(node, axis)
+          container = node.parent
+          container = container.parent while container&.anonymous? && container.main_axis == axis
+          unless container
+            all = @graph.roots.map { |r| @boxes[r.id] }
+            return [all.map { |b| axis.leading_edge(b) }.min, all.map { |b| axis.trailing_edge(b) }.max]
+          end
+
+          box = @boxes[container.id]
+          padding = container.layout_padding(@theme)
+          title = axis == Axis::HEIGHT ? container.layout_title_height(@theme) : 0.0
+          [axis.leading_edge(box) + padding + title, axis.trailing_edge(box) - padding]
+        end
+
+        def shift(node, axis, delta)
+          return if delta.abs < EPSILON
+
+          box = @boxes[node.id]
+          axis.set_position(box, axis.position(box) + delta)
+          node.children.each { |c| shift(c, axis, delta) }
+        end
+
+        # An anonymous layer/stack's box follows its children (it draws nothing, but routing and the
+        # alignment of its own parent read it).
+        def refit(container, axis)
+          while container&.anonymous?
+            boxes = container.children.map { |c| @boxes[c.id] }
+            box = @boxes[container.id]
+            lead = boxes.map { |b| axis.leading_edge(b) }.min
+            trail = boxes.map { |b| axis.trailing_edge(b) }.max
+            axis.set_position(box, (lead + trail) / 2.0)
+            axis.set_size(box, trail - lead)
+            container = container.parent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archsight/diagram/layout/expander.rb

@@ -46,6 +46,7 @@ module Archsight
             # tied to its box size in ways that break if stretched to match
             # an unrelated, much larger sibling).
             return if target_size <= current
+            return if natural_size?(node)
             return unless node.representer.stretchable?
 
             axis.set_size(box, target_size)
@@ -109,6 +110,7 @@ module Archsight
               node.children.each do |c|
                 expand(c, axis, inner, inherited: extend)
                 axis.set_position(@boxes[c.id], center)
+                place_natural(c, axis, inner, center) if natural_size?(c)
               end
             end
             return
@@ -121,6 +123,17 @@ module Archsight
           expand(node.children.first, axis, own_target - inset(node, axis), inherited: extend)
         end
 
+        # A leaf with `extend "false"` keeps its own size inside a wider stack or layer.
+        def natural_size?(node) = node.leaf? && node.attrs["extend"] == "false"
+
+        # Puts such a leaf at its `anchor` (centered by default) inside the `room` long stretch of `axis`
+        # around `center` that its stack or layer gave it.
+        def place_natural(node, axis, room, center)
+          box = @boxes[node.id]
+          extra = [room - axis.size(box), 0.0].max
+          axis.set_position(box, center - (room / 2.0) + (axis.size(box) / 2.0) + node.anchor_shift(axis, extra, default: :center))
+        end
+
         # `extend "height"`: grows `node` to `target` height keeping its
         # content top-aligned (or at its `anchor`), then hands the extra room to whatever inside
         # can absorb it -- a `stack` child carrying `extend "height"`

data/lib/archsight/diagram/layout/ports.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require_relative "../support/text_metrics"
+
+module Archsight
+  module Diagram
+    class Layout
+      # The size of a port's tab (see `Graph::Port`): its label in monospace at the edge-label font size, a
+      # little padding around it, and room for its badge dot.
+      class PortMetrics
+        PADDING_X = 6.0
+        PADDING_Y = 4.5
+        BADGE_ROOM = 10.0
+        # Never closer to a corner of the leaf than this, never closer to the next tab than `GAP`.
+        MARGIN = 10.0
+        GAP = 8.0
+
+        def initialize(theme)
+          @theme = theme
+        end
+
+        def font_size = @theme.edge_label_font_size
+        def height = font_size + (2 * PADDING_Y)
+
+        def width(port)
+          chars = TextMetrics.lines(port.label).map { |line| TextMetrics.markdown_runs(line).sum { |content, _| content.length } }.max
+          (chars * TextMetrics::MONO_WIDTH * font_size / 1000.0) + (2 * PADDING_X) + (port.badge ? BADGE_ROOM : 0.0)
+        end
+
+        # The length a side needs to hold `ports` side by side (`along` is the tab's size along that side).
+        def side_length(ports, &)
+          return 0.0 if ports.empty?
+
+          ports.sum(&) + (GAP * (ports.length - 1)) + (2 * MARGIN)
+        end
+
+        # `[min width, min height]` of a leaf with `ports`. A port without a `side` may end up on either
+        # side of the leaf, so it counts for the top and bottom alike (where most ports go).
+        def leaf_minimum(ports)
+          on = ->(side) { ports.select { |p| p.side == side || (p.side.nil? && %w[top bottom].include?(side)) } }
+          tab_height = height
+          [%w[top bottom].map { |side| side_length(on.call(side)) { |p| width(p) } }.max,
+           %w[left right].map { |side| side_length(on.call(side)) { tab_height } }.max]
+        end
+      end
+
+      # Puts every port's tab on its leaf's border, once the leaves have their final position: on its `side`
+      # (or the side facing what its edges connect it to), at its `at` (or lined up with what its edges
+      # connect it to, when that does not span the whole side; else spread in declaration order), the tabs of
+      # one side never overlapping. A tab straddles the border, half inside the leaf. Two rounds, so ports
+      # whose edges connect them to other ports settle on each other's place.
+      class PortPlacement
+        HORIZONTAL_SIDES = %i[top bottom].freeze
+
+        def initialize(graph, boxes, theme:)
+          @graph = graph
+          @boxes = boxes
+          @metrics = PortMetrics.new(theme)
+        end
+
+        # `{ "node.port" => Box }`
+        def place
+          ports = @graph.ports
+          return {} if ports.empty?
+
+          tabs = {}
+          2.times { tabs = place_all(ports, tabs) }
+          tabs.each_value(&:freeze_bounds!)
+          tabs
+        end
+
+        private
+
+        def place_all(ports, previous)
+          sides = Hash.new { |h, k| h[k] = [] }
+          ports.each_with_index do |port, index|
+            box = @boxes[port.node.id]
+            peers = peer_boxes(port, previous)
+            side = (port.side || facing_side(box, peers)).to_sym
+            width = @metrics.width(port)
+            along = HORIZONTAL_SIDES.include?(side) ? width : @metrics.height
+            wanted = port.at ? at_position(box, side, port.at, along) : preference(box, side, peers)
+            sides[[port.node.id, side]] << { port: port, along: along, width: width, wanted: wanted, index: index }
+          end
+
+          sides.each_with_object({}) do |((node_id, side), members), tabs|
+            box = @boxes[node_id]
+            spread(box, side, members).each { |m| tabs[m[:port].ref] = tab_box(box, side, m[:position], m[:width]) }
+          end
+        end
+
+        # The boxes at the other ends of `port`'s edges: the peer's tab once it is placed, else its leaf.
+        def peer_boxes(port, previous)
+          @graph.edges.filter_map do |edge|
+            if edge.from_port.equal?(port)
+              (edge.to_port && previous[edge.to_port.ref]) || @boxes[edge.to.id]
+            elsif edge.to_port.equal?(port)
+              (edge.from_port && previous[edge.from_port.ref]) || @boxes[edge.from.id]
+            end
+          end
+        end
+
+        # The side whose outside the peers' mean center lies furthest beyond (top without peers).
+        def facing_side(box, peers)
+          return "top" if peers.empty?
+
+          dx = (peers.sum(&:x) / peers.length) - box.x
+          dy = (peers.sum(&:y) / peers.length) - box.y
+          if dy.abs - (box.height / 2.0) >= dx.abs - (box.width / 2.0)
+            dy.negative? ? "top" : "bottom"
+          else
+            dx.negative? ? "left" : "right"
+          end
+        end
+
+        # Where along its side a port lines up with its peers: the mean of their centers, leaving out a peer
+        # that spans the whole side (it lines up anywhere). `nil` when no peer has a preference.
+        def preference(box, side, peers)
+          lo, hi = side_range(box, side)
+          centers = peers.filter_map do |peer|
+            peer_lo, peer_hi, center = span(peer, side)
+            center unless peer_lo <= lo && peer_hi >= hi
+          end
+          centers.empty? ? nil : centers.sum / centers.length
+        end
+
+        def at_position(box, side, at, along)
+          lo, hi = side_range(box, side)
+          case at
+          when "left", "top" then lo + (along / 2.0)
+          when "right", "bottom" then hi - (along / 2.0)
+          when "center" then (lo + hi) / 2.0
+          else lo + (along / 2.0) + ((hi - lo - along) * at.to_f / 100.0)
+          end
+        end
+
+        # Ports without a preference share the side evenly in declaration order, then every port is pushed
+        # just far enough for the tabs not to overlap and to stay inside the side.
+        def spread(box, side, members)
+          lo, hi = side_range(box, side)
+          free = members.select { |m| m[:wanted].nil? }
+          free.each_with_index { |m, i| m[:wanted] = lo + ((hi - lo) * (i + 0.5) / free.length) }
+
+          ordered = members.sort_by { |m| [m[:wanted], m[:index]] }
+          ordered.each { |m| m[:position] = m[:wanted].clamp(lo + half(m), [lo + half(m), hi - half(m)].max) }
+          ordered.each_cons(2) { |a, b| b[:position] = [b[:position], a[:position] + apart(a, b)].max }
+          last = ordered.last
+          last[:position] = [last[:position], hi - half(last)].min
+          ordered.reverse.each_cons(2) { |b, a| a[:position] = [a[:position], b[:position] - apart(a, b)].min }
+          ordered
+        end
+
+        def half(member) = member[:along] / 2.0
+
+        # How far apart the centers of two neighbouring tabs must be.
+        def apart(one, other) = half(one) + half(other) + PortMetrics::GAP
+
+        # The part of a side a tab may sit on: inside the leaf's corners.
+        def side_range(box, side)
+          if HORIZONTAL_SIDES.include?(side)
+            [box.left + PortMetrics::MARGIN, box.right - PortMetrics::MARGIN]
+          else
+            [box.top + PortMetrics::MARGIN, box.bottom - PortMetrics::MARGIN]
+          end
+        end
+
+        def span(peer, side)
+          HORIZONTAL_SIDES.include?(side) ? [peer.left, peer.right, peer.x] : [peer.top, peer.bottom, peer.y]
+        end
+
+        def tab_box(box, side, position, width)
+          case side
+          when :top then Box.new(position, box.top, width, @metrics.height)
+          when :bottom then Box.new(position, box.bottom, width, @metrics.height)
+          when :left then Box.new(box.left, position, width, @metrics.height)
+          else Box.new(box.right, position, width, @metrics.height)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/archsight/diagram/layout/rank_arranger.rb

@@ -101,6 +101,30 @@ module Archsight
         # up, not necessarily through the narrow strip between the ranks, so
         # widening the strip for it doesn't reliably help and just leaves an
         # oversized gap.
+        # How much further apart two ranks go because port tabs stick out of the sides they face (half a tab
+        # each), keyed like `Stacker#pack`'s gaps.
+        def port_overhangs(children)
+          metrics = PortMetrics.new(@theme)
+          children.each_cons(2).with_object({}) do |(a, b), gaps|
+            extra = overhang(a, "bottom", metrics) + overhang(b, "top", metrics)
+            gaps[[a.id, b.id].sort] = extra if extra.positive?
+          end
+        end
+
+        # Half a tab if a port sits on `side` of `node`, or of a leaf an anonymous layer/stack puts on that side
+        # (a named container's padding already leaves room). A port without a `side` may end up on any side.
+        def overhang(node, side, metrics)
+          if node.leaf?
+            node.ports.any? { |p| p.side.nil? || p.side == side } ? metrics.height / 2.0 : 0.0
+          elsif !node.anonymous? || node.children.empty?
+            0.0
+          elsif node.stack?
+            overhang(side == "top" ? node.children.first : node.children.last, side, metrics)
+          else
+            node.children.map { |c| overhang(c, side, metrics) }.max
+          end
+        end
+
         def arrange_stack(group, children)
           return if children.empty?
 
@@ -114,8 +138,10 @@ module Archsight
             children, axis: Axis::HEIGHT, default_gap: group.gap(@theme.stack_gap),
                       related_gap: group.gap(@theme.sibling_gap),
                       label_gaps: @rank_topology.rank_label_gaps(rank_edges),
-                      related_pairs: rank_edges.map { |(ra, rb, _e)| [ra.id, rb.id].sort }
+                      related_pairs: rank_edges.map { |(ra, rb, _e)| [ra.id, rb.id].sort },
+                      extra_gaps: port_overhangs(children)
           )
+          children.each { |c| expander.place_natural(c, Axis::WIDTH, max_width, max_width / 2.0) if expander.natural_size?(c) }
         end
       end
     end

data/lib/archsight/diagram/layout/stacker.rb

@@ -28,7 +28,8 @@ module Archsight
         # `related_pairs`, otherwise `default_gap`; a label gap is only a
         # minimum on top of that (room for the label), so it can widen the
         # gap but never shrink a larger one -- e.g. an explicit `gap "150"`.
-        def pack(children, axis:, default_gap:, related_gap:, label_gaps: {}, related_pairs: [])
+        # `extra_gaps` (by sorted id pair) is added on top of the pair's gap, e.g. for port tabs sticking out.
+        def pack(children, axis:, default_gap:, related_gap:, label_gaps: {}, related_pairs: [], extra_gaps: {})
           return if children.empty?
 
           cross = axis.cross
@@ -40,7 +41,7 @@ module Archsight
             unless i.zero?
               pair = [children[i - 1].id, c.id].sort
               base = related_pairs.include?(pair) ? related_gap : default_gap
-              pos += [label_gaps[pair], base].compact.max
+              pos += [label_gaps[pair], base].compact.max + extra_gaps.fetch(pair, 0.0)
             end
 
             size = axis.size(box)

data/lib/archsight/diagram/layout.rb

@@ -16,6 +16,8 @@ require_relative "layout/ranked_arranger"
 require_relative "layout/rank_arranger"
 require_relative "layout/root_alignment"
 require_relative "layout/globalizer"
+require_relative "layout/alignment"
+require_relative "layout/ports"
 require_relative "legend"
 
 module Archsight
@@ -74,8 +76,9 @@ module Archsight
       # font sizes/title offsets the boxes were sized for; `legend` (a
       # `Legend::Placement`, or nil for none) is where the legend went --
       # its boxes are in `boxes` like any node's.
-      Result = Struct.new(:boxes, :width, :height, :theme, :legend, keyword_init: true) do
-        def initialize(theme: Theme::DEFAULT, **) = super
+      # `ports` holds each port's tab (`{ "node.port" => Box }`, see `PortPlacement`).
+      Result = Struct.new(:boxes, :width, :height, :theme, :legend, :ports, keyword_init: true) do
+        def initialize(theme: Theme::DEFAULT, ports: {}, **) = super
       end
 
       # Pairs a Graph::Node with its computed Box, for the routing stages
@@ -129,10 +132,11 @@ module Archsight
           @root_alignment.align_connected_roots
         end
         @globalizer.globalize_all(@graph.roots)
+        Alignment.new(@graph, @boxes, theme: @theme).apply
         legend = place_legend
         normalize_to_canvas
         @boxes.each_value(&:freeze_bounds!)
-        Result.new(boxes: @boxes, width: @canvas_width, height: @canvas_height, theme: @theme, legend: legend)
+        Result.new(boxes: @boxes, width: @canvas_width, height: @canvas_height, theme: @theme, legend: legend, ports: place_ports)
       end
 
       # See `Layout.attach_legend`: the canvas only ever grows to take the
@@ -145,11 +149,13 @@ module Archsight
         frame = @boxes[legend.frame.id]
         width = [result.width, frame.right + @theme.canvas_margin].max
         height = [result.height, frame.bottom + @theme.canvas_margin].max
-        Result.new(boxes: @boxes, width: width, height: height, theme: @theme, legend: legend)
+        Result.new(boxes: @boxes, width: width, height: height, theme: @theme, legend: legend, ports: result.ports)
       end
 
       private
 
+      def place_ports = PortPlacement.new(@graph, @boxes, theme: @theme).place
+
       # Bottom-up: determine width/height for every node, and (for groups)
       # position children relative to the group's own local origin (0, 0).
       def size_and_place(node)
@@ -177,7 +183,11 @@ module Archsight
         return text_size(node, extra_height) if node.kind == :text
 
         width = [label_width(node) + @theme.node_label_padding, @theme.node_min_width].max
-        [width, @theme.node_height + extra_height]
+        height = @theme.node_height + extra_height
+        return [width, height] if node.ports.empty?
+
+        min_width, min_height = PortMetrics.new(@theme).leaf_minimum(node.ports)
+        [[width, min_width].max, [height, min_height].max]
       end
 
       # A text node has no box to pad out: one line height per line and a little air, and no minimum width, so a

data/lib/archsight/diagram/legend/inventory.rb

@@ -10,6 +10,7 @@ module Archsight
       # decides *how* those rows look once assembled. `relations` are the
       # relations actually drawn (see `Legend.rows`).
       class Inventory
+        Attributes = Graph::Attributes
         def initialize(graph, relations:)
           @graph = graph
           @relations = relations
@@ -18,7 +19,7 @@ module Archsight
         def rows
           return @rows if defined?(@rows)
 
-          @rows = trivial? ? [] : shape_rows + relation_rows + dataflow_rows + swatch_rows
+          @rows = trivial? ? [] : shape_rows + port_rows + relation_rows + line_rows + dataflow_rows + swatch_rows + badge_rows
         end
 
         private
@@ -28,7 +29,29 @@ module Archsight
         def trivial?
           (used_shapes - ["rectangle"]).empty? && @relations.all? { |r| Relations.for(r).default? } &&
             !boundary_present? && !application_present? && @graph.dataflows.empty? && used_tints.empty? &&
-            tinted_containers.empty?
+            tinted_containers.empty? && @graph.ports.empty? && used_badges.empty? && used_lines.empty?
+        end
+
+        def port_rows = @graph.ports.empty? ? [] : [PortRow.new("Port")]
+
+        # A row per line style that is drawn and has its legend text from a top-level `line "..." { label }`.
+        def line_rows = used_lines.map { |d| LineRow.new(d.label, line_style: d.id) }
+
+        def badge_rows = used_badges.map { |d| BadgeRow.new(d.label, tint: d.tint, badge: d.id) }
+
+        def used_lines
+          @used_lines ||= Attributes::LINE_STYLES.filter_map do |style|
+            definition = @graph.line_definition(style)
+            definition if definition && @graph.edges.any? { |e| e.line_style == style && @relations.include?(e.relation) }
+          end
+        end
+
+        # Badges in the order they are defined.
+        def used_badges
+          @used_badges ||= begin
+            ids = (@graph.nodes_by_id.values.filter_map(&:badge) + @graph.ports.filter_map(&:badge)).uniq
+            @graph.definitions.values.select { |d| d.kind == :badge && ids.include?(d.id) }
+          end
         end
 
         def shape_rows
@@ -62,9 +85,34 @@ module Archsight
           rows << SwatchRow.new("Trust boundary", tint: Tints.for("red"), dash_class: "asd-swatch-boundary") if default_boundary_present?
           tinted_containers.each do |n|
             dash_class = n.boundary? ? "asd-swatch-boundary" : "asd-swatch-container"
-            rows << SwatchRow.new(MarkdownText.like(n.label, "#{n.kind.to_s.capitalize} #{n.label}"), tint: Tints.for(n.effective_tint), dash_class: dash_class)
+            label = n.legend_label || MarkdownText.like(n.label, "#{n.kind.to_s.capitalize} #{n.label}")
+            rows << SwatchRow.new(label, tint: Tints.for(n.effective_tint), dash_class: dash_class)
           end
-          rows + used_tints.map { |t| SwatchRow.new(t.name.capitalize, tint: t) }
+          rows + tint_rows
+        end
+
+        # One row per tint set on a leaf, named by a `legend "..."` of one of those leaves, else by the leaves'
+        # own names -- not by the color, which says nothing. Left out when every such leaf sits inside a
+        # container of the same tint, whose own row already explains it.
+        def tint_rows
+          used_tints.filter_map do |tint|
+            leaves = tinted_leaves.select { |n| n.tint == tint.name }
+            next if leaves.all? { |n| inside_same_tinted_container?(n) }
+
+            label = leaves.filter_map(&:legend_label).first || leaves.map { |n| display_name(n) }.uniq.join(", ")
+            SwatchRow.new(label, tint: tint)
+          end
+        end
+
+        def tinted_leaves = @graph.nodes_by_id.values.reject { |n| n.container? || n.kind == :text || n.tint.nil? }
+
+        def inside_same_tinted_container?(node)
+          node.ancestors.drop(1).any? { |a| !a.anonymous? && a.tint == node.tint }
+        end
+
+        # A node's name as its label shows it: the first line, without markdown markers.
+        def display_name(node)
+          TextMetrics.markdown_runs(TextMetrics.lines(node.label).first).map(&:first).join.strip
         end
 
         def used_shapes

data/lib/archsight/diagram/legend/row.rb

@@ -138,6 +138,50 @@ module Archsight
           m.to_s
         end
       end
+
+      # A port tab (see `NodeRenderer#render_ports`).
+      class PortRow < Row
+        def id_key = "port"
+
+        def icon(cx, cy, id:)
+          m = Renderer::Markup.new
+          m.element("rect", id: "#{id}__icon", x: SvgFormat.fmt(cx - 11), y: SvgFormat.fmt(cy - 6), width: 22, height: 12, rx: 3,
+                            class: %w[asd-port asd-stroke-blue-0])
+          m.to_s
+        end
+      end
+
+      # A dashed/dotted edge line, explained by a top-level `line "dashed" { label "..." }`.
+      class LineRow < Row
+        def initialize(label, line_style:)
+          super(label)
+          @line_style = line_style
+        end
+
+        def id_key = "line-#{@line_style}"
+
+        def icon(cx, cy, id:)
+          legend_line_sample(cx, cy, css_class: ["asd-relation-dependency", "asd-stroke-thin", "asd-line-#{@line_style}"],
+                                     marker_id: Renderer::MarkerDefs.marker_id("dependency"), id: "#{id}__icon")
+        end
+      end
+
+      # A badge dot (`badge "id" { tint; label }`).
+      class BadgeRow < Row
+        def initialize(label, tint:, badge:)
+          super(label)
+          @tint = tint
+          @badge = badge
+        end
+
+        def id_key = "badge-#{Renderer::ElementIds.slug(@badge)}"
+
+        def icon(cx, cy, id:)
+          m = Renderer::Markup.new
+          m.element("circle", id: "#{id}__icon", cx: SvgFormat.fmt(cx), cy: SvgFormat.fmt(cy), r: 4, class: "asd-badge-#{@tint}")
+          m.to_s
+        end
+      end
     end
   end
 end

data/lib/archsight/diagram/parser/ast.rb

@@ -51,6 +51,15 @@ module Archsight
       # A top-level diagram-wide `key "value"` setting -- currently only
       # `theme "compact"` (see `Theme`).
       Setting = Struct.new(:key, :value, :line, keyword_init: true)
+
+      # `port "id" { label "..."; side "top"; at "left"; badge "..." }` inside a leaf: a labelled tab on
+      # the leaf's border that edges attach to (`a -> leaf.id`). Its id is local to the leaf.
+      Port = Struct.new(:id, :attrs, :line, keyword_init: true)
+
+      # A top-level legend definition: `badge "id" { tint "orange"; label "..." }` (a dot nodes and
+      # ports carry with `badge "id"`) or `line "dashed" { label "..." }` (the legend text of edges
+      # drawn with `line "dashed"`). `kind` is :badge or :line.
+      Definition = Struct.new(:kind, :id, :attrs, :line, keyword_init: true)
     end
   end
 end