etassia 0.1.0

data/lib/etassia/layout/timeline.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "timeline_flow"
+require_relative "../diagram/timeline"
+require_relative "../notation/mermaid/ir_adapters/timeline"
+
+module Etassia
+  module Layout
+    # Builds final timeline geometry for the SVG renderer, placing cards
+    # where mmdc places them.
+    class Timeline < Base
+      # mmdc's left margin: the base arrow starts here.
+      AXIS_X = 150
+      # Space around the drawing in the viewBox.
+      FRAME = 50
+      TITLE_Y = 20
+      TITLE_ASCENT = 31
+      TITLE_SIZE = 33
+      EMPTY_AXIS_WIDTH = 300
+
+      class Scene < Layout::Scene
+        attribute :id, :string
+        attribute :view_box, :string
+        attribute :acc_title, :string
+        attribute :acc_description, :string
+        attribute :title, :string
+        attribute :title_x, :float
+        attribute :title_y, :float
+        attribute :title_size, :float
+        attribute :cards, TimelineCard, collection: true,
+                                        default: -> { [] }
+        attribute :axis, TimelineLine
+      end
+
+      private
+
+      def scene(diagram)
+        document = ir_document(diagram)
+        sectioned = sectioned?(document)
+        flow = TimelineFlow.new(
+          groups(document), sectioned: sectioned, font_size: card_font_size
+        )
+        shift_to_origin(build_scene(document, flow))
+      end
+
+      def card_font_size
+        value = theme.typography&.font_size_large
+        value&.positive? ? value : TimelineText::FONT_SIZE
+      end
+
+      def build_scene(document, flow)
+        cards = flow.cards
+        left, right = card_span(cards)
+        frame(document, cards, base_arrow(flow.axis_y, left, right),
+              ((right - left) / 2.0) - AXIS_X)
+      end
+
+      def frame(document, cards, axis, title_x)
+        Scene.new(
+          id: document.id, acc_title: document.accessibility_title,
+          acc_description: document.accessibility_description,
+          title: document.label, title_x: title_x, title_y: TITLE_Y,
+          title_size: TITLE_SIZE, cards: cards, axis: axis
+        )
+      end
+
+      def card_span(cards)
+        return [0, 0] if cards.empty?
+
+        ranges = cards.map(&:x_range)
+        [ranges.map(&:first).min, ranges.map(&:last).max]
+      end
+
+      def base_arrow(axis_y, left, right)
+        TimelineLine.new(
+          x1: AXIS_X, y1: axis_y, x2: (right - left) + (3 * AXIS_X),
+          y2: axis_y, stroke_width: 4
+        )
+      end
+
+      # Moves the drawing so its viewBox starts at the origin.
+      def shift_to_origin(scene)
+        delta_x = FRAME - left_edge(scene)
+        delta_y = FRAME - top_edge(scene)
+        scene.cards.each { |card| card.shift(delta_x, delta_y) }
+        scene.axis.shift(delta_x, delta_y)
+        move_title(scene, delta_x, delta_y)
+        size(scene)
+      end
+
+      def move_title(scene, delta_x, delta_y)
+        scene.title_x = TimelineRounding.tidy(scene.title_x + delta_x)
+        scene.title_y = TimelineRounding.tidy(scene.title_y + delta_y)
+      end
+
+      def size(scene)
+        width = scene.axis.x2 + FRAME
+        height = bottom_edge(scene) + FRAME
+        scene.width = TimelineRounding.tidy(width)
+        scene.height = TimelineRounding.tidy(height)
+        scene.view_box = "0 0 #{scene.width} #{scene.height}"
+        scene
+      end
+
+      def left_edge(scene)
+        edges = scene.cards.map { |card| card.x_range.first }
+        edges << AXIS_X
+        edges << scene.title_x if scene.title
+        edges.min
+      end
+
+      def top_edge(scene)
+        edges = scene.cards.map(&:y) << scene.axis.y1
+        edges << (TITLE_Y - TITLE_ASCENT) if scene.title
+        edges.min
+      end
+
+      def bottom_edge(scene)
+        scene.cards.map(&:bottom).push(scene.axis.y1).max
+      end
+
+      def ir_document(diagram)
+        return diagram if diagram.is_a?(IR::Prepositioned)
+
+        Notation::Mermaid::IRAdapters::Timeline.call(diagram)
+      end
+
+      def sectioned?(document)
+        document.items.any? { |item| item.role == "section" }
+      end
+
+      # mmdc draws only the periods inside a section once the diagram has
+      # one; periods written before the first section are not drawn.
+      def groups(document)
+        sections = items(document, "section")
+        return [{ name: nil, periods: periods(document, nil) }] if
+          sections.empty?
+
+        sections.map do |section|
+          { name: section.label, periods: periods(document, section.id) }
+        end
+      end
+
+      def periods(document, parent_id)
+        items(document, "event", parent_id).map do |event|
+          { name: event_time(event),
+            events: items(document, "description", event.id).map(&:label) }
+        end
+      end
+
+      def items(document, role, parent_id = :any)
+        document.items.select do |item|
+          next false unless item.role == role
+
+          parent_id == :any || item.parent_id == parent_id
+        end
+      end
+
+      def event_time(event)
+        event.placements.find { |item| item.dimension == "time" }.value.value
+      end
+    end
+  end
+end

data/lib/etassia/layout/timeline_card.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "timeline_line"
+require_relative "timeline_rounding"
+require_relative "timeline_text"
+
+module Etassia
+  module Layout
+    # One fully positioned line of text inside a timeline card.
+    class TimelineTextRun < Lutaml::Model::Serializable
+      attribute :content, :string
+      attribute :x, :float
+      attribute :y, :float
+    end
+
+    # One timeline box: a section, a period or an event.
+    class TimelineCard < Lutaml::Model::Serializable
+      attribute :kind, :string
+      attribute :lines, :string, collection: true, default: -> { [] }
+      attribute :x, :float
+      attribute :y, :float
+      attribute :width, :float
+      attribute :height, :float
+      attribute :text_width, :float
+      attribute :color_index, :integer
+      attribute :font_size, :float
+      # The dashed line a period drops towards its events.
+      attribute :connector, TimelineLine
+      # Canvas path data of the box, rounded top corners and open bottom.
+      attribute :outline, :string
+      # The rule under the box, on the canvas.
+      attribute :rule, TimelineLine
+      # Canvas anchor of the first text line, centred on the box.
+      attribute :text_x, :float
+      attribute :text_y, :float
+      # Canvas baselines of the text lines after the first.
+      attribute :next_baselines, :float, collection: true, default: -> { [] }
+      attribute :text_runs, TimelineTextRun,
+                collection: true,
+                default: -> { [] }
+
+      CORNER = 5
+      TEXT_TOP = 10
+      FIRST_BASELINE = 21
+      LINE_PITCH = 17.6
+
+      # Moves the card, and its connector, by the given offsets.
+      def shift(delta_x, delta_y)
+        self.x += delta_x
+        self.y += delta_y
+        connector&.shift(delta_x, delta_y)
+        place
+      end
+
+      # Publishes the canvas geometry the renderer draws from.
+      def place
+        settle
+        self.outline = outline_path
+        self.rule = rule_line
+        place_text
+      end
+
+      # @return [Float] x range the box and its text cover
+      def x_range
+        reach = [width, text_width].max
+        middle = x + (width / 2)
+        [middle - (reach / 2), middle + (reach / 2)]
+      end
+
+      # @return [Float] lowest y the box or its connector reaches
+      def bottom
+        [y + height, connector&.y2].compact.max
+      end
+
+      private
+
+      def settle
+        %i[x y width height text_width].each do |name|
+          public_send(:"#{name}=", tidy(public_send(name)))
+        end
+        connector&.settle
+      end
+
+      def place_text
+        self.text_x = tidy(x + (width / 2))
+        self.text_y = tidy(y + TEXT_TOP + scaled_text(FIRST_BASELINE))
+        publish_text_lines
+      end
+
+      def publish_text_lines
+        self.next_baselines = baselines_after_first
+        self.text_runs = positioned_text_runs
+      end
+
+      def positioned_text_runs
+        lines.each_with_index.map do |content, index|
+          TimelineTextRun.new(
+            content: content, x: text_x,
+            y: index.zero? ? nil : next_baselines.fetch(index - 1)
+          )
+        end
+      end
+
+      def baselines_after_first
+        pitch = scaled_text(LINE_PITCH)
+        (1...lines.length).map { |i| tidy(text_y + (i * pitch)) }
+      end
+
+      def scaled_text(value)
+        size = font_size&.positive? ? font_size : TimelineText::FONT_SIZE
+        value * size / TimelineText::FONT_SIZE.to_f
+      end
+
+      def tidy(value)
+        TimelineRounding.tidy(value)
+      end
+
+      def rule_line
+        bottom_y = tidy(y + height)
+        TimelineLine.new(x1: x, y1: bottom_y, x2: tidy(x + width),
+                         y2: bottom_y)
+      end
+
+      def outline_path
+        [start_command, "v#{path_number(CORNER + CORNER - height)}",
+         "q0,-#{CORNER} #{CORNER},-#{CORNER}", "h#{path_number(width - 10)}",
+         "q#{CORNER},0 #{CORNER},#{CORNER}", "v#{path_number(height - CORNER)}",
+         "H#{path_number(x)}", "Z"].join(" ")
+      end
+
+      def start_command
+        "M#{path_number(x)} #{path_number(y + height - CORNER)}"
+      end
+
+      def path_number(value)
+        tidied = tidy(value)
+        tidied.to_i == tidied ? tidied.to_i.to_s : tidied.to_s
+      end
+    end
+  end
+end

data/lib/etassia/layout/timeline_flow.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "timeline_card"
+require_relative "timeline_text"
+
+module Etassia
+  module Layout
+    # Places timeline cards on mmdc's fixed grid: 200 units per period,
+    # sections above their periods, events stacked under each period.
+    #
+    # Two numbers mmdc takes from a measuring pass are reproduced as it
+    # takes them: every period is measured with the text "[object Object]"
+    # (it passes the period object, not its name), and an event stack is
+    # measured without the 50 unit minimum the drawn cards get.
+    class TimelineFlow
+      LEFT = 200
+      TOP = 50
+      COLUMN = 200
+      TEXT_WIDTH = 150
+      CARD_WIDTH = 190
+      MIN_EVENT = 50
+      EVENT_GAP = 10
+      EVENT_DROP = 200
+      PERIOD_MEASURE = "[object Object]"
+
+      # @param groups [Array<Hash>] {name:, periods: [{name:, events:}]};
+      #   one unnamed group when the diagram has no sections
+      # @param sectioned [Boolean] whether groups are drawn as sections
+      def initialize(groups, sectioned:, font_size: TimelineText::FONT_SIZE)
+        @groups = groups
+        @sectioned = sectioned
+        @font_size = font_size
+        @periods = groups.flat_map { |group| group[:periods] }
+      end
+
+      # @return [Array<TimelineCard>] in drawing order
+      def cards
+        @cards ||= @sectioned ? sectioned_cards : unsectioned_cards
+      end
+
+      # @return [Float] y of the base arrow
+      def axis_y
+        return task_max + 100 unless @sectioned
+
+        section_max + task_max + 150
+      end
+
+      private
+
+      def unsectioned_cards
+        period_cards(@periods, 0, [LEFT, TOP])
+      end
+
+      def sectioned_cards
+        left = LEFT
+        @groups.each_with_index.flat_map do |group, index|
+          columns = [group[:periods].length, 1].max
+          group_cards(group, index, left, columns).tap do
+            left += COLUMN * columns
+          end
+        end
+      end
+
+      def group_cards(group, index, left, columns)
+        origin = [left, TOP + section_max + 50]
+        [section_card(group[:name], columns, index, left),
+         *period_cards(group[:periods], index, origin)]
+      end
+
+      def section_card(name, columns, index, left)
+        width = (COLUMN * columns) - 50
+        lines = wrap(name, width)
+        height = [card_height(lines), section_max].max
+        card("section", lines, [left, TOP, width + 40, height], index)
+      end
+
+      def period_cards(periods, color, origin)
+        running = task_max
+        periods.flat_map.with_index do |period, index|
+          card = period_card(period[:name], shifted(origin, index), running,
+                             color)
+          running = [running, card.height].max
+          card.connector = connector(card, running, origin.last)
+          [card, *event_cards(period[:events], card, color)]
+        end
+      end
+
+      def shifted(origin, index)
+        [origin.first + (COLUMN * index), origin.last]
+      end
+
+      def period_card(name, origin, running, color)
+        lines = wrap(name, TEXT_WIDTH)
+        height = [card_height(lines), running].max
+        card("period", lines, [*origin, CARD_WIDTH, height], color)
+      end
+
+      def event_cards(events, period, color)
+        top = period.y + EVENT_DROP
+        events.map do |text|
+          lines = wrap(text, TEXT_WIDTH)
+          height = [card_height(lines), MIN_EVENT].max
+          card("event", lines, [period.x, top, CARD_WIDTH, height], color)
+            .tap { top += EVENT_GAP + height }
+        end
+      end
+
+      def connector(period, running, top)
+        TimelineLine.new(
+          x1: period.x + 95, y1: top + running, x2: period.x + 95,
+          y2: top + running + EVENT_DROP + event_stack_max,
+          stroke_width: 2, dashed: true
+        )
+      end
+
+      def card(kind, lines, box, color)
+        x, y, width, height = box
+        TimelineCard.new(
+          kind: kind, lines: lines.reject(&:empty?), x: x, y: y,
+          width: width, height: height, color_index: color,
+          font_size: @font_size,
+          text_width: lines.map { |line| text_width(line) }.max
+        ).tap(&:place)
+      end
+
+      def section_max
+        @section_max ||= @groups.map do |group|
+          measured(group[:name]) + TimelineText::PADDING
+        end.max.to_f
+      end
+
+      def task_max
+        @task_max ||= @periods.empty? ? 0.0 : measured(PERIOD_MEASURE) + 20
+      end
+
+      def event_stack_max
+        @event_stack_max ||=
+          @periods.map { |period| stack(period[:events]) }.max.to_f
+      end
+
+      def stack(events)
+        return 0 if events.empty?
+
+        events.sum { |text| measured(text) } + (EVENT_GAP * (events.length - 1))
+      end
+
+      def measured(text)
+        card_height(wrap(text, TEXT_WIDTH))
+      end
+
+      def wrap(text, width)
+        TimelineText.wrap(text, width, font_size: @font_size)
+      end
+
+      def card_height(lines)
+        TimelineText.card_height(lines, font_size: @font_size)
+      end
+
+      def text_width(line)
+        TimelineText.width_of(line, font_size: @font_size)
+      end
+    end
+  end
+end

data/lib/etassia/layout/timeline_line.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "timeline_rounding"
+
+module Etassia
+  module Layout
+    # A straight timeline line with an arrowhead at its far end.
+    class TimelineLine < Lutaml::Model::Serializable
+      attribute :x1, :float
+      attribute :y1, :float
+      attribute :x2, :float
+      attribute :y2, :float
+      attribute :stroke_width, :float
+      attribute :dashed, :boolean, default: -> { false }
+
+      # Moves the line by the given offsets.
+      def shift(delta_x, delta_y)
+        self.x1 += delta_x
+        self.x2 += delta_x
+        self.y1 += delta_y
+        self.y2 += delta_y
+        settle
+      end
+
+      # Rounds the end points to the published precision.
+      def settle
+        self.x1, self.x2, self.y1, self.y2 =
+          [x1, x2, y1, y2].map { |value| TimelineRounding.tidy(value) }
+      end
+    end
+  end
+end

data/lib/etassia/layout/timeline_rounding.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Layout
+    # Rounds published timeline coordinates so sums such as 100.6 + 11
+    # never leave float noise in the scene.
+    module TimelineRounding
+      # Decimal places of every published timeline coordinate.
+      PLACES = 4
+
+      module_function
+
+      # @return [Float] the value without accumulated float noise
+      def tidy(value)
+        value.to_f.round(PLACES)
+      end
+    end
+  end
+end

data/lib/etassia/layout/timeline_text.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../text_measurement"
+require_relative "../text_measurement/trebuchet_advances"
+
+module Etassia
+  module Layout
+    # Wraps and sizes timeline card text the way mmdc does: words are added
+    # to a line until it passes the card text width, then the line breaks.
+    # Widths are Trebuchet MS advances, the face mmdc measured with.
+    class TimelineText
+      FONT_SIZE = 16
+      FIRST_LINE_HEIGHT = 19.0
+      NEXT_LINE_HEIGHT = 17.6
+      # Space under the text that every card keeps, besides its padding.
+      TEXT_MARGIN = FONT_SIZE * 1.1 * 0.5
+      PADDING = 20
+      TOKENS = /(\s+|<br>)/
+      BREAK = "<br>"
+      TABLE = TextMeasurement::TrebuchetAdvances::TABLE
+      DESIGN_UNITS_PER_EM = 2048.0
+      BASIC_LATIN_START = 0x20
+      # Exact hmtx units for U+0020..U+007E in Trebuchet MS Regular. The
+      # shared per-mille table intentionally rounds each glyph; long labels
+      # accumulate those sub-unit losses before the browser measures them.
+      BASIC_LATIN_UNITS = %w[
+        617 752 665 1074 1074 1229 1446 327 752 752 752 1074 752 752 752 1074
+        1074 1074 1074 1074 1074 1074 1074 1074 1074 1074 752 752 1074 1074
+        1074 752 1578 1208 1159 1225 1256 1097 1075 1385 1340 570 976 1179
+        1037 1453 1307 1380 1142 1384 1192 985 1189 1328 1203 1745 1140 1168
+        1127 752 728 752 1074 1074 1074 1076 1141 1014 1141 1117 757 1028
+        1119 584 751 1033 604 1700 1119 1099 1141 1141 796 829 812 1119 1003
+        1524 1026 1010 972 752 1074 752 1074
+      ].map!(&:to_i).freeze
+
+      class << self
+        # @param text [String] label text, possibly holding <br>
+        # @param width [Numeric] text width at which a line breaks
+        # @return [Array<String>] the lines, whitespace collapsed
+        def wrap(text, width, font_size: FONT_SIZE)
+          lines = []
+          line = []
+          text.to_s.split(TOKENS).each do |word|
+            line << word
+            next unless line_break?(word, line, width, font_size)
+
+            line.pop
+            lines << join(line)
+            line = word == BREAK ? [""] : [word]
+          end
+          lines << join(line)
+        end
+
+        # @return [Float] width of one line in user units
+        def width_of(line, font_size: FONT_SIZE)
+          units = join([line]).each_char.sum { |char| design_units(char) }
+          units * font_size / DESIGN_UNITS_PER_EM
+        end
+
+        # @return [Float] height of the drawn text, blank lines not counted
+        def text_height(lines, font_size: FONT_SIZE)
+          drawn = lines.count { |line| !line.empty? }
+          return 0.0 if drawn.zero?
+
+          scaled(FIRST_LINE_HEIGHT, font_size) +
+            ((drawn - 1) * scaled(NEXT_LINE_HEIGHT, font_size))
+        end
+
+        # @return [Float] card height the text needs before any minimum
+        def card_height(lines, font_size: FONT_SIZE)
+          margin = scaled(TEXT_MARGIN, font_size)
+          text_height(lines, font_size: font_size) + margin + PADDING
+        end
+
+        private
+
+        def line_break?(word, line, width, font_size)
+          word == BREAK || width_of(join(line), font_size: font_size) > width
+        end
+
+        def join(words)
+          words.join(" ").gsub(/\s+/, " ").strip
+        end
+
+        def advance(char)
+          TABLE.fetch(char.ord) do
+            TextMeasurement.measure(char, font_size: 1000)[:width]
+          end
+        end
+
+        def design_units(char)
+          index = char.ord - BASIC_LATIN_START
+          return BASIC_LATIN_UNITS.fetch(index) if
+            index.between?(0, BASIC_LATIN_UNITS.length - 1)
+
+          (advance(char) * DESIGN_UNITS_PER_EM / 1000).round
+        end
+
+        def scaled(value, font_size)
+          value * font_size / FONT_SIZE.to_f
+        end
+      end
+    end
+  end
+end