etassia 0.1.0

data/lib/etassia/source.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Etassia
+  # Separates a Mermaid source's preamble from its diagram body.
+  #
+  # Mermaid allows three things before the diagram keyword: a YAML
+  # frontmatter block, `%%{init: ...}%%` directives, and `%%` comments.
+  # Split them together, not with three separate calls — `%%{` is also a
+  # valid `%%` comment opener, so the ordering is part of the lexing.
+  #
+  # @example
+  #   Source.split("---\ntitle: T\n---\nflowchart LR\n  A-->B\n")
+  #   # => { frontmatter: "title: T\n", directives: [],
+  #          body: "flowchart LR\n..." }
+  class Source
+    # Malformed frontmatter is an error, not an absent title. Collapsing
+    # the two meant etassia rendered `title: [` and a duplicated title,
+    # both of which mermaid refuses.
+    class MalformedFrontmatter < StandardError; end
+
+    # A frontmatter block: `---` alone on a line, YAML, then `---` alone
+    # again. The fences must be indented the SAME amount — mermaid accepts
+    # a matching indent and rejects a mismatched one, and 44 corpus cases
+    # are damaged in exactly that way (opener at column 0, closer indented).
+    # At least one line has to sit between the fences: mermaid rejects an
+    # empty block.
+    FRONTMATTER = /\A([ \t]*)---[ \t]*\n(.+?)^\1---[ \t]*(?:\n|\z)/m
+
+    # A byte order mark is a byte like any other to mermaid's frontmatter
+    # regex, which is why a BOM in front of a fence costs the title. It is
+    # not part of the diagram, though, so it comes off before anything is
+    # detected.
+    BOM = /\A\uFEFF/
+
+    # A comment line that is not the start of a directive. A bare `%%` is
+    # one too: eight diagram types refuse it and fifteen render it, so the
+    # split takes it either way and `Engine` asks the type.
+    COMMENT = /\A[ \t]*%%(?!\{)[^\n]*(?:\n|\z)/
+
+    # A `%%` with NOTHING after it on its line — not even a space. mmdc
+    # renders `%% ` and `%%\t` in front of a flowchart and refuses a bare
+    # `%%`, so the trailing whitespace is what makes it a comment.
+    BARE_COMMENT = /\A[ \t]*%%(?:\n|\z)/
+
+    # Mermaid's own directive scan: `%%{`, a header word with or without a
+    # colon, then a value that is either a bare word or everything up to
+    # the first `}%%`.
+    #
+    # Keep the terminator OPTIONAL: `%%{init: {}` alone on a line must
+    # still swallow the diagram with it, matching mmdc's refusal.
+    #
+    # A value starting with a word character ends where that word ends
+    # (`%%{init: x` takes "x"); every other shape (`{`, a quote, a bracket,
+    # no value) reaches forward for `}%%` and takes the rest of the file
+    # when there is none.
+    DIRECTIVE = /\A[ \t]*%%\{\s*(?:\w+\s*:|\w+)
+                 \s*(?:\w+|(?:(?!\}%%).|\n)*)?\s*(?:\}%%)?/x
+
+    # A `%%{` that scan will not take — no header word — is not a directive
+    # to mermaid at all. It falls through to the comment pass, which eats
+    # the whole LINE, `}%%` and all. That is the shape, and the shape
+    # decides the verdict: `%%{}%%flowchart LR` loses the keyword with the
+    # line, `%%{\n}%%` strands a `}%%` in front of the body, and mmdc
+    # refuses both for all 23 types. Only a `%%{}%%` sitting alone on its
+    # line costs the body nothing, and that one is type-dependent.
+    DEGENERATE_DIRECTIVE = /\A[ \t]*%%\{[^\n]*(?:\n|\z)/
+    BLANK_LINE = /\A[ \t]*\n/
+
+    class << self
+      # Splits a source into its preamble parts and its body.
+      #
+      # @param source [String] raw Mermaid source
+      # @return [Hash] :frontmatter (String or nil), :directives (Array),
+      #   :body (String), and :degenerate — the preamble items only some
+      #   diagram types tolerate
+      # Frontmatter is read before the BOM comes off or comments are consumed;
+      # a later fence can be removed from the body but does not provide title.
+      def split(source)
+        scanner = StringScanner.new(normalize(source))
+        frontmatter = take_frontmatter(scanner)
+        scanner.skip(BOM)
+        directives, degenerate = take_preamble(scanner)
+        { frontmatter: frontmatter, directives: directives,
+          body: scanner.rest, degenerate: degenerate }
+      end
+
+      # Reads the `title` out of a frontmatter block.
+      #
+      # @param frontmatter [String, nil] the YAML block, without its fences
+      # @return [String, nil] the title mermaid would draw, or nil when it
+      #   would draw none
+      # @raise [MalformedFrontmatter] when mermaid's loader would refuse
+      #   the document
+      #
+      # Never add a `strip.empty?` shortcut here: an empty-or-blank block is
+      # `Frontmatter`'s own answer to give, and short-circuiting past it
+      # makes this disagree with `Frontmatter.new(x).title` on invalid bytes.
+      def title(frontmatter)
+        return nil if frontmatter.nil?
+
+        Frontmatter.new(frontmatter).title
+      end
+
+      private
+
+      # Decodes to valid UTF-8 first, since every pattern below and in the
+      # parsers raises on invalid bytes. Mermaid treats a lone \r as a line
+      # ending too, and leaving them in leaks carriage returns into labels
+      # and geometry downstream.
+      def normalize(source)
+        decode(source).gsub(/\r\n?/, "\n")
+      end
+
+      # mmdc reads its input as UTF-8 and draws U+FFFD for every invalid
+      # run, so that is what every type gets: one valid UTF-8 string, before
+      # any regexp or grammar sees it. `String#scrub` makes the same runs
+      # as node's decoder.
+      #
+      # A string tagged BINARY or US-ASCII carries no encoding of its own
+      # (`File.binread`, `$stdin.read` under `LANG=C`), so its bytes are read
+      # as UTF-8, as mmdc reads a file. A string tagged with a real encoding
+      # is transcoded instead; an encoding Ruby has no converter for (EUC-TW,
+      # for one) falls back to the byte reading.
+      def decode(source)
+        case source.encoding
+        when Encoding::UTF_8
+          source.scrub
+        when Encoding::BINARY, Encoding::US_ASCII
+          source.dup.force_encoding(Encoding::UTF_8).scrub
+        else
+          transcode(source)
+        end
+      end
+
+      # CESU-8 and the three UTF8-* carrier encodings come out of `encode`
+      # tagged UTF-8 with their bytes unchecked, so the result is retagged
+      # through its bytes to make `scrub` look at them.
+      def transcode(source)
+        source.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+          .b.force_encoding(Encoding::UTF_8).scrub
+      rescue Encoding::ConverterNotFoundError
+        source.b.force_encoding(Encoding::UTF_8).scrub
+      end
+
+      def take_frontmatter(scanner)
+        return nil unless scanner.scan(FRONTMATTER)
+
+        dedent(scanner[2], scanner[1])
+      end
+
+      def dedent(yaml, indent)
+        return yaml if indent.empty?
+
+        yaml.gsub(/^#{Regexp.escape(indent)}/, "")
+      end
+
+      # A fence met here is never frontmatter — it stays in the text for
+      # the diagram's own parser, and `Engine` asks the type whether that
+      # is fatal. Exception: once a bare `%%` or headerless `%%{...}%%` has
+      # been erased, leave the fence in the body — mermaid deletes those
+      # lines whole, which would otherwise leave the fence standing at the
+      # front of the file where every type refuses it.
+      #
+      # Walk with a scanner instead of re-slicing the rest per item, which
+      # is quadratic over a long run of comments.
+      def take_preamble(scanner)
+        directives = []
+        degenerate = []
+        erased = false
+        while (state = consume_preamble_item(
+          scanner, directives, degenerate, erased
+        ))
+          erased = state.first
+        end
+        [directives, degenerate.uniq]
+      end
+
+      def consume_preamble_item(scanner, directives, degenerate, erased)
+        return [erased] if scanner.skip(BLANK_LINE)
+        return take_directive(scanner, directives, erased) if
+          scanner.match?(DIRECTIVE)
+
+        return take_degenerate_directive(scanner, degenerate) if
+          scanner.skip(DEGENERATE_DIRECTIVE)
+        return take_comment(scanner, degenerate, erased) if
+          scanner.match?(COMMENT)
+
+        take_late_frontmatter_unless_erased(scanner, degenerate, erased)
+      end
+
+      def take_late_frontmatter_unless_erased(scanner, degenerate, erased)
+        return if erased || !scanner.skip(FRONTMATTER)
+
+        take_late_frontmatter(scanner, degenerate)
+      end
+
+      def take_directive(scanner, directives, erased)
+        directives << scanner.scan(DIRECTIVE).strip
+        [erased]
+      end
+
+      def take_degenerate_directive(_scanner, degenerate)
+        degenerate << :directive
+        [true]
+      end
+
+      def take_comment(scanner, degenerate, erased)
+        bare = scanner.match?(BARE_COMMENT)
+        degenerate << :comment if bare
+        scanner.skip(COMMENT)
+        [erased || bare]
+      end
+
+      def take_late_frontmatter(_scanner, degenerate)
+        degenerate << :frontmatter
+        [false]
+      end
+    end
+  end
+end
+
+require_relative "source/frontmatter"

data/lib/etassia/svg/arrowhead.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require_relative "escaping"
+require_relative "numbers"
+require_relative "path_geometry"
+require_relative "polygon"
+
+module Etassia
+  module Svg
+    # Draws the arrowheads a path asks for.
+    #
+    # SVG Tiny 1.2 (:metanorma profile) has no way to reference a
+    # <marker>, so marker-end="url(#...)" resolves to nothing -- draw
+    # the head directly here rather than adding <marker>/<defs> wiring.
+    #
+    # A head hidden under its node (centre-to-centre edges) is
+    # Engine#layout_graph's bug, not this class's.
+    class Arrowhead
+      # Chosen by eye as stroke-width multiples so the head scales with the
+      # line. These are not derived from mermaid-js's marker proportions.
+      LENGTH = 4.0
+      HALF_WIDTH = 2.0
+
+      # An unset stroke-width paints a 1-unit line, per SVG.
+      DEFAULT_STROKE_WIDTH = 1.0
+
+      # SVG's own "no marker here", and its initial `stroke`. A path carrying
+      # either is asking for nothing to be drawn, which is not the same as
+      # not having asked.
+      NONE = "none"
+      PAINT_ATTRIBUTES = {
+        fill_opacity: :stroke_opacity,
+        opacity: :opacity,
+        transform: :transform,
+      }.freeze
+      private_constant :LENGTH, :HALF_WIDTH, :DEFAULT_STROKE_WIDTH, :NONE,
+                       :PAINT_ATTRIBUTES
+
+      # @param path [Svg::Path] the path to draw arrowheads for
+      # @return [Array<Svg::Polygon>] one per marker the path asked for
+      def self.for(path)
+        new(path).polygons
+      end
+
+      def initialize(path)
+        @path = path
+      end
+
+      # Reads the path's data at most once, and not at all when no marker was
+      # asked for — which is most paths. Nothing is cached on the instance:
+      # the path is mutable, so a remembered geometry would answer for a `d`
+      # the caller has since replaced.
+      #
+      # A head the path gave no heading for is dropped rather than returned as
+      # nil, so a position in the result names a head only when both were
+      # asked for and both could be drawn.
+      #
+      # @return [Array<Svg::Polygon>] the end-marker head before the
+      #   start-marker head, with either absent
+      def polygons
+        heads = requested_heads
+        return [] if heads.empty?
+
+        # An arrowhead is the end of the line, so a line painting nothing
+        # ends in nothing. SVG's initial `stroke` is `none`, and inherited
+        # paint is not visible from here, so an unstroked path gets no head
+        # rather than a black one floating free of it.
+        return [] unless painted?
+
+        geometry = PathGeometry.new(path.d)
+        heads.filter_map { |head| triangle(anchor_for(head, geometry)) }
+      end
+
+      private
+
+      attr_reader :path
+
+      def requested_heads
+        markers = [[:end, path.marker_end], [:start, path.marker_start]]
+        markers.filter_map do |head, marker|
+          head if names_something?(marker)
+        end
+      end
+
+      def anchor_for(head, geometry)
+        return geometry.terminus if head == :end
+
+        reversed(geometry.origin)
+      end
+
+      # Asked of a marker and of a stroke alike, because `none` is SVG's own
+      # "nothing here" for both. Escaping.blank? catches an unset attribute;
+      # an attribute set to `''` or to whitespace is set, and still names
+      # nothing.
+      #
+      # @param value [Object] an attribute value
+      # @return [Boolean] whether it names something rather than nothing
+      def names_something?(value)
+        return false if Escaping.blank?(value)
+
+        named = value.to_s.strip.downcase
+        !named.empty? && named != NONE
+      end
+
+      # A line paints only if it names a colour AND has a width to paint it
+      # with. SVG Tiny 1.2 gives `stroke-width="0"` no stroke at all, so a
+      # head there would be the same free-floating triangle an unset stroke
+      # would have left.
+      #
+      # @return [Boolean] whether the path paints a stroke at all
+      def painted?
+        names_something?(path.stroke) && stroke_width.positive?
+      end
+
+      # Unlike marker orient="auto", which points along the path, Etassia
+      # deliberately reverses a start head to form a bidirectional arrow. No
+      # renderer sets marker_start, so this deviation is reached only by a
+      # caller assigning `path.marker_start=` directly -- Path.from_xml no
+      # longer exists to reach it either.
+      def reversed(anchor)
+        anchor && PathGeometry::Anchor.new(anchor.x, anchor.y,
+                                           -anchor.dx, -anchor.dy)
+      end
+
+      # @param anchor [PathGeometry::Anchor, nil] tip and heading
+      # @return [Svg::Polygon, nil] nil when the path gave no heading to
+      #   point the arrowhead along or a computed corner is non-finite
+      def triangle(anchor)
+        return nil if anchor.nil?
+
+        coordinates = corners(anchor)
+        return nil unless coordinates.flatten.all?(&:finite?)
+
+        Polygon.new.tap do |polygon|
+          set_points(polygon, coordinates)
+          copy_paint(polygon)
+        end
+      end
+
+      def set_points(polygon, coordinates)
+        written = coordinates.map do |x, y|
+          [Numbers.write(x), Numbers.write(y)]
+        end
+        polygon.points = Polygon.build_points(written)
+      end
+
+      # The head is painted where the line's stroke would have been, so it
+      # inherits the line's opacity and sits in its coordinate space.
+      def copy_paint(polygon)
+        polygon.fill = path.stroke
+        PAINT_ATTRIBUTES.each do |target, source|
+          value = presence(path.public_send(source))
+          polygon.public_send("#{target}=", value)
+        end
+      end
+
+      # Tip on the path's end, base one arrow-length back along the heading,
+      # squared off either side of it.
+      def corners(anchor)
+        tip = anchor.to_a.first(2)
+        base = arrow_base(anchor)
+        offset = corner_offset(anchor)
+        [tip, subtract(base, offset), add(base, offset)]
+      end
+
+      def arrow_base(anchor)
+        length = LENGTH * stroke_width
+        [anchor.x - (anchor.dx * length),
+         anchor.y - (anchor.dy * length)]
+      end
+
+      def corner_offset(anchor)
+        half = HALF_WIDTH * stroke_width
+        [anchor.dy * half, -anchor.dx * half]
+      end
+
+      def add(left, right)
+        left.zip(right).map(&:sum)
+      end
+
+      def subtract(left, right)
+        left.zip(right).map { |a, b| a - b }
+      end
+
+      # nil rather than lutaml's unset sentinel or an empty attribute value,
+      # neither of which should be handed to a new polygon.
+      def presence(value)
+        value unless Escaping.blank?(value) || value.to_s.strip.empty?
+      end
+
+      # Zero remains zero because it suppresses the stroke. Unset,
+      # unreadable, non-finite, and negative widths fall back because SVG
+      # ignores those error values and uses the inherited or initial width.
+      # Non-finite widths are guarded here before multiplication. A finite
+      # width can still overflow as the corners are computed, so #triangle
+      # rejects that non-finite result instead of writing it into points.
+      def stroke_width
+        width = Numbers.read(path.stroke_width)
+        return DEFAULT_STROKE_WIDTH unless width&.finite? && !width.negative?
+
+        width
+      end
+    end
+  end
+end

data/lib/etassia/svg/circle.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Circle element <circle>
+    #
+    # Represents a circle shape with center point and radius.
+    class Circle < Element
+      attribute :cx, :float
+      attribute :cy, :float
+      attribute :r, :float
+
+      writes_attributes :cx, :cy, :r
+    end
+  end
+end

data/lib/etassia/svg/document.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Document root element
+    #
+    # Represents the top-level <svg> element with namespace declarations,
+    # viewBox, and dimension attributes. Contains all other SVG elements
+    # as children.
+    class Document < Lutaml::Model::Serializable
+      SVG_NAMESPACE = "http://www.w3.org/2000/svg"
+      XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/"
+      SVG_VERSION = "1.2"
+      SVG_BASE_PROFILE = "tiny"
+
+      attribute :width, :float
+      attribute :height, :float
+      attribute :view_box, :string
+      attribute :version, :string
+      attribute :base_profile, :string
+      attribute :xmlns, :string
+      attribute :overflow, :string
+      attribute :children, Element, collection: true
+
+      # Initialize document with calculated viewBox if not provided
+      #
+      # @param width [Numeric] Document width
+      # @param height [Numeric] Document height
+      # @param view_box [String] ViewBox specification
+      # @param overflow [String, nil] SVG `overflow` presentation attribute,
+      #   e.g. `'hidden'`. Omitted from the output when nil, which is every
+      #   renderer but flowchart's today — see `Flowchart#render`.
+      def initialize(
+        width: nil, height: nil, view_box: nil, overflow: nil, **args
+      )
+        super(**args)
+        self.width = width
+        self.height = height
+        self.view_box = view_box || calculate_view_box(width, height)
+        self.version = SVG_VERSION
+        self.base_profile = SVG_BASE_PROFILE
+        self.xmlns = SVG_NAMESPACE
+        self.overflow = overflow
+        self.children = []
+      end
+
+      # Add an element to the document
+      #
+      # @param element [Element] SVG element to add
+      # @return [void]
+      def add_element(element)
+        children << element
+      end
+
+      alias << add_element
+
+      # Generate SVG XML string
+      #
+      # @return [String] XML representation of the SVG document
+      def to_xml
+        parts = ["<svg"]
+        parts.concat(document_xml_attributes)
+        parts << ">"
+
+        append_xml_children(parts)
+
+        parts << "</svg>"
+        parts.join("\n")
+      end
+
+      # String representation returns XML
+      alias to_s to_xml
+
+      private
+
+      def document_xml_attributes
+        document_attribute_pairs.each_with_object([]) do |(name, value), pairs|
+          pairs << Escaping.attribute(name, value) unless value.nil?
+        end
+      end
+
+      def document_attribute_pairs
+        [
+          ["width", width], ["height", height], ["viewBox", view_box],
+          ["version", version], ["baseProfile", base_profile],
+          ["xmlns", xmlns], ["overflow", overflow]
+        ]
+      end
+
+      def append_xml_children(parts)
+        children.each do |child|
+          parts << child.to_xml if child.respond_to?(:to_xml)
+        end
+      end
+
+      def calculate_view_box(width, height)
+        return nil unless width && height
+
+        "0 0 #{width} #{height}"
+      end
+    end
+  end
+end