etassia 0.1.0

data/lib/etassia/svg/element.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "escaping"
+require "lutaml/model"
+require_relative "numbers"
+require_relative "style"
+
+module Etassia
+  module Svg
+    # Base class for all SVG elements.
+    #
+    # Provides common attributes and functionality shared by all SVG elements
+    # including styling, transformation, and identification.
+    class Element < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :class_name, :string
+      attribute :style, Svg::Style
+      attribute :transform, :string
+      attribute :fill, :string
+      attribute :fill_opacity, :string
+      attribute :stroke, :string
+      attribute :stroke_width, :string
+      attribute :stroke_opacity, :string
+      attribute :opacity, :string
+
+      # class_name is the only reader whose SVG name is not just its own
+      # with underscores hyphenated.
+      ATTRIBUTE_NAMES = { class_name: "class" }.freeze
+      private_constant :ATTRIBUTE_NAMES
+
+      # The SVG name for a Ruby attribute reader.
+      #
+      # @param name [Symbol] the reader
+      # @return [String] the attribute name to emit
+      def self.svg_name(name)
+        ATTRIBUTE_NAMES.fetch(name) { name.to_s.tr("_", "-") }
+      end
+      private_class_method :svg_name
+
+      # Emitted by every element, in this order, as [svg name, reader].
+      # Named once here rather than on every render.
+      #
+      # `opacity` is not in the list even though it is an attribute. SVG Tiny
+      # 1.2 — the element and attribute table the svg_conform :metanorma
+      # profile enforces — has no `opacity` property, only `fill-opacity` and
+      # `stroke-opacity`. So the two opacity readers below fold it in rather
+      # than emitting it, and every element inherits that by construction.
+      BASE_PAIRS = [
+        [svg_name(:id), :id],
+        [svg_name(:class_name), :class_name],
+        [svg_name(:transform), :transform],
+        [svg_name(:fill), :fill],
+        [svg_name(:fill_opacity), :painted_fill_opacity],
+        [svg_name(:stroke), :stroke],
+        [svg_name(:stroke_width), :stroke_width],
+        [svg_name(:stroke_opacity), :painted_stroke_opacity],
+      ].map(&:freeze).freeze
+      private_constant :BASE_PAIRS
+
+      # Generate XML representation of this element.
+      #
+      # A fragment, not a document. An element that draws sibling shapes — a
+      # Path with an arrowhead — returns more than one root, and a strict
+      # parser will refuse that as having two roots. Group and Document join
+      # fragments, so that is the contract they already rely on. Path calls
+      # it on each of its own arrowheads too, and a Polygon draws no
+      # siblings, so those are always one root.
+      #
+      # @return [String] one or more sibling elements, newline separated
+      def to_xml
+        xml_lines.join("\n")
+      end
+
+      # Declares the attributes an element writes, in output order.
+      #
+      # Several subclasses were each carrying the same shape of method — a
+      # list of names paired with the matching reader. Declaring them removes
+      # that repetition and, more usefully, removes the chance of one class's
+      # version drifting into a different shape.
+      #
+      # Ruby names map to SVG names by turning underscores into hyphens, which
+      # covers every attribute these elements emit (`stroke_dasharray` becomes
+      # `stroke-dasharray`). A notation needing anything else should override
+      # #element_attributes rather than bend this.
+      #
+      # @param names [Array<Symbol>] attribute readers, in output order
+      # @return [void]
+      def self.writes_attributes(*names)
+        pairs = names.map { |name| [svg_name(name), name].freeze }.freeze
+        define_method(:element_attributes) { attribute_pairs(pairs) }
+
+        # define_method defines a public method, while the base hook is
+        # protected. Without this a declared subclass widened the API for no
+        # reason and disagreed with its own parent.
+        protected :element_attributes
+      end
+
+      protected
+
+      # The complete markup for one element.
+      #
+      # @return [String] XML string
+      def element_markup
+        tag = self.class.name.split("::").last.downcase
+        attrs = build_attributes
+
+        "<#{tag}#{attrs}/>"
+      end
+
+      # The markup a parent indents, one entry per structural unit.
+      #
+      # Separate from #to_xml because a parent may not indent every line of a
+      # child's markup: a Text holding a newline would have its content
+      # rewritten. Group indents entries instead, and Text#element_markup is
+      # the only entry that may carry a newline of its own.
+      #
+      # @return [Array<String>] this element's markup, then each sibling's
+      #   markup
+      def xml_lines
+        [element_markup, *sibling_markup]
+      end
+
+      # Hook for subclasses to draw sibling shapes alongside this element.
+      #
+      # @return [Array<String>] one entry of markup per sibling
+      def sibling_markup
+        []
+      end
+
+      # Build attribute string for XML output
+      #
+      # @return [String] formatted attribute string
+      def build_attributes
+        Escaping.attributes(attribute_pairs(BASE_PAIRS) + element_attributes)
+      end
+
+      # Reads the current values for already-named attributes.
+      #
+      # Shared with .writes_attributes so the base attributes and a
+      # subclass's own go through one naming rule. Written out as literal
+      # pairs in both places, the hyphenation was typed by hand here and
+      # computed there, which is two spellings of one rule.
+      #
+      # `send`, not `public_send`: some pair-table readers are protected:
+      # #painted_fill_opacity and #painted_stroke_opacity here, plus
+      # Text#offset_x and Text#baseline_y in the subclass. `public_send`
+      # cannot reach them.
+      #
+      # @param pairs [Array<Array>] [svg name, reader], in output order
+      # @return [Array<Array>] name/value pairs
+      def attribute_pairs(pairs)
+        pairs.map { |svg_name, reader| [svg_name, send(reader)] }
+      end
+
+      # `fill-opacity` as it should be painted, with any whole-element
+      # `opacity` folded in.
+      #
+      # @return [Object, nil] the attribute value, or nil when unset
+      def painted_fill_opacity
+        composed_opacity(fill_opacity)
+      end
+
+      # `stroke-opacity` as it should be painted, with any whole-element
+      # `opacity` folded in.
+      #
+      # @return [Object, nil] the attribute value, or nil when unset
+      def painted_stroke_opacity
+        composed_opacity(stroke_opacity)
+      end
+
+      # Hook for subclasses to add their specific attributes.
+      #
+      # Returns name/value PAIRS, not rendered markup. That is deliberate: it
+      # leaves Escaping.attributes as the only code that turns an attribute
+      # into text, so a subclass cannot emit an unescaped one. Pairs with a
+      # nil value are dropped, so callers need no conditionals.
+      #
+      # @return [Array<Array>] name/value pairs
+      def element_attributes
+        []
+      end
+
+      private
+
+      # Multiplies a component opacity by the whole-element one.
+      #
+      # Approximate where fill/stroke overlap (no object opacity in
+      # SVG Tiny 1.2) -- accepted deviation, not a bug to fix here.
+      # NOT equivalent to Group opacity -- do not reuse this for a
+      # container. Non-numeric/non-finite components are left alone,
+      # never clamped, to avoid emitting an invented value.
+      #
+      # @param component [Object] fill-opacity or stroke-opacity as set
+      # @return [Object, nil] the value to emit
+      def composed_opacity(component)
+        whole = Numbers.read(opacity)
+        return component if whole.nil?
+
+        part = Escaping.blank?(component) ? 1.0 : Numbers.read(component)
+        return component if part.nil?
+        return component unless whole.finite? && part.finite?
+
+        whole = whole.clamp(0.0, 1.0)
+        part = part.clamp(0.0, 1.0)
+        Numbers.write(part * whole)
+      end
+    end
+  end
+end

data/lib/etassia/svg/ellipse.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Ellipse element <ellipse>
+    #
+    # Represents an ellipse shape with center point and radii.
+    class Ellipse < Element
+      attribute :cx, :float
+      attribute :cy, :float
+      attribute :rx, :float
+      attribute :ry, :float
+
+      # Emitted nothing before this: an Ellipse rendered as
+      # `<ellipse fill="red"/>` with no geometry, and renderer/c4.rb:242 draws
+      # boundaries with it.
+      writes_attributes :cx, :cy, :rx, :ry
+    end
+  end
+end

data/lib/etassia/svg/escaping.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Etassia
+  module Svg
+    # XML escaping for everything Etassia writes into an SVG document.
+    #
+    # Nothing was escaped before this. A diagram label reading
+    # `Alice<img src=` was emitted verbatim, which is malformed XML and, since
+    # our SVG is embedded directly into Metanorma documents, lets diagram
+    # source become markup in a rendered document.
+    #
+    # Two entry points because the rules differ. Text content only has to
+    # protect the three characters that can start markup or an entity.
+    # Attribute values additionally sit inside quotes, so both quote
+    # characters have to go too.
+    #
+    # Each is a single pass over a character map rather than a chain of
+    # replacements: escaping `&` after `<` would turn `&lt;` into `&amp;lt;`,
+    # and a one-pass substitution cannot make that mistake regardless of the
+    # order the map is written in.
+    module Escaping
+      TEXT = {
+        "&" => "&amp;",
+        "<" => "&lt;",
+        ">" => "&gt;",
+      }.freeze
+
+      ATTRIBUTE = TEXT.merge(
+        '"' => "&quot;",
+        "'" => "&apos;",
+      ).freeze
+
+      # Derived from the maps, never written out again. A hand-kept pattern
+      # drifts: add a character to a map, forget the regex, and that character
+      # silently stops being escaped while every test still passes.
+      TEXT_PATTERN = Regexp.union(TEXT.keys).freeze
+      ATTRIBUTE_PATTERN = Regexp.union(ATTRIBUTE.keys).freeze
+
+      # XML 1.0 forbids these code points entirely: they have no escape, so a
+      # document containing one is unparseable whatever you do to the rest.
+      # Tab, newline and carriage return are the only C0 characters allowed.
+      # Characters past U+FFFF (emoji among them) are allowed.
+      # A sequence label accepts any non-line-ending character
+      # (grammars/sequence.rb:241), so a NUL in a diagram reached the output
+      # and xmllint refused the SVG.
+      FORBIDDEN = /[^\t\n\r\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/
+
+      module_function
+
+      # Removes characters XML cannot represent at all.
+      #
+      # Dropping rather than substituting: there is no legal escape for them,
+      # and inventing a replacement character would put content in the document
+      # that the author never wrote.
+      def strip_forbidden(text)
+        text.gsub(FORBIDDEN, "")
+      end
+
+      # Escapes a value destined for element text content.
+      #
+      # @param value [Object] the value, stringified first
+      # @return [String] the escaped text
+      def escape_text(value)
+        strip_forbidden(value.to_s).gsub(TEXT_PATTERN, TEXT)
+      end
+
+      # Escapes a value destined for a double-quoted attribute.
+      #
+      # @param value [Object] the value, stringified first
+      # @return [String] the escaped value
+      def escape_attribute(value)
+        strip_forbidden(value.to_s).gsub(ATTRIBUTE_PATTERN, ATTRIBUTE)
+      end
+
+      # An XML attribute name: a letter or underscore, then name characters.
+      # Deliberately narrow — SVG attribute names are ASCII with hyphens and
+      # the occasional colon.
+      NAME = /\A[A-Za-z_][\w.:-]*\z/
+
+      # Renders one name/value pair as a leading-space XML attribute.
+      #
+      # This is the only place an attribute becomes text. Subclasses hand back
+      # pairs rather than markup, so there is no second path to keep in sync.
+      #
+      # The NAME check is not decoration: a pair whose name was
+      # `x="safe" onload` produced a valid document with an extra injected
+      # attribute, because only the value was ever escaped.
+      #
+      # @param name [String] the attribute name
+      # @param value [Object] the attribute value
+      # @return [String] ` name="escaped"`
+      # @raise [ArgumentError] if the name is not a valid XML attribute name
+      def attribute(name, value)
+        return "" if blank?(value)
+
+        unless name.to_s.match?(NAME)
+          raise ArgumentError, "not a valid attribute name: #{name.inspect}"
+        end
+
+        %( #{name}="#{escape_attribute(value)}")
+      end
+
+      # Renders name/value pairs, skipping any whose value is nil.
+      #
+      # @param pairs [Array<Array>] name/value pairs
+      # @return [String] the concatenated attributes
+      # @raise [ArgumentError] if handed anything but a pair
+      def attributes(pairs)
+        pairs.filter_map { |pair| render(pair) }.join
+      end
+
+      # @api private
+      def render(pair)
+        name, value = as_pair(pair)
+
+        attribute(name, value) unless blank?(value)
+      end
+
+      # lutaml-model leaves an unset attribute holding an UninitializedClass
+      # sentinel rather than nil, and that object returns ITSELF from both
+      # to_s and gsub. So it slipped past a nil check and past escaping, and
+      # `Text.from_xml("<text>x</text>").to_xml` emitted
+      # `fill-opacity="#<Lutaml::Model::UninitializedClass:0x...>"` — whose raw
+      # `<` makes the document unparseable.
+      #
+      # Tested on to_s rather than on the sentinel's class name: any object
+      # whose to_s does not return a String cannot be escaped, and matching a
+      # class name by string would break the moment lutaml renames it.
+      #
+      # @api private
+      def blank?(value)
+        value.nil? || !value.to_s.is_a?(String)
+      end
+
+      # The pairs contract is what makes the escaping boundary provable, so a
+      # subclass still returning rendered markup has to fail loudly. Dropping
+      # it silently would lose every attribute on that element.
+      #
+      # @api private
+      def as_pair(pair)
+        return pair if pair.is_a?(Array) && pair.size == 2
+
+        raise ArgumentError,
+              "expected a [name, value] pair, got #{pair.inspect}. " \
+              "element_attributes returns pairs, not rendered markup."
+      end
+    end
+  end
+end

data/lib/etassia/svg/group.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Group element <g>
+    #
+    # Groups multiple SVG elements together for collective transformation
+    # and styling. Implements the Composite pattern for hierarchical
+    # SVG structure.
+    class Group < Element
+      attribute :children, Element, collection: true
+      # PlantUML marks a class member's visibility icon with it.
+      attribute :data_visibility_modifier, :string
+
+      writes_attributes :data_visibility_modifier
+
+      def initialize(**args)
+        super
+        self.children ||= []
+      end
+
+      # Add a child element to this group
+      #
+      # @param element [Element] SVG element to add
+      # @return [void]
+      def add_child(element)
+        children << element
+      end
+
+      alias << add_child
+
+      protected
+
+      # The open tag, each child's entries indented one level, then the close
+      # tag.
+      #
+      # Indents entries rather than lines: a Text holding a newline would
+      # otherwise have its own content indented along with the markup.
+      #
+      # `children` is a plain Array that enforces no type, so a caller can put
+      # anything in one; nothing in the gem does. A foreign object is skipped
+      # rather than serialized. That narrows the old test — anything answering
+      # to `to_xml` used to be written out — because indenting a child by its
+      # entries needs the entries, and only an Element has them.
+      #
+      # @return [Array<String>] structural lines for this group
+      def xml_lines
+        attrs = build_attributes
+
+        return ["<g#{attrs}/>"] if children.empty?
+
+        child_lines = children.flat_map do |child|
+          next [] unless child.is_a?(Element)
+
+          child.xml_lines.map { |line| "  #{line}" }
+        end
+        ["<g#{attrs}>", *child_lines, "</g>"]
+      end
+    end
+  end
+end

data/lib/etassia/svg/line.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Line element <line>
+    #
+    # Represents a straight line between two points.
+    class Line < Element
+      attribute :x1, :float
+      attribute :y1, :float
+      attribute :x2, :float
+      attribute :y2, :float
+      attribute :stroke_dasharray, :string
+
+      writes_attributes :x1, :y1, :x2, :y2, :stroke_dasharray
+    end
+  end
+end

data/lib/etassia/svg/numbers.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "escaping"
+
+module Etassia
+  module Svg
+    # Reading and writing the numbers that end up in SVG attributes.
+    #
+    # `read` copes with more than Float(): lutaml-model leaves an unset
+    # attribute holding a sentinel object rather than nil, renderers
+    # assign opacities as strings, and a font size may carry a unit
+    # (14px). Anything it can't parse comes back nil -- treat that as
+    # "not set", never as zero.
+    module Numbers
+      # A leading SVG number: optional sign, digits with an optional decimal
+      # part, optional exponent. Anything after it (a `px` unit, whitespace)
+      # is ignored rather than rejected.
+      LEADING = /\A\s*[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/
+
+      # Computed coordinates are floats, so 12.0 * 1.1 lands on
+      # 13.200000000000001 rather than 13.2. Four decimals is finer than
+      # any diagram needs and short enough to read in a diff.
+      PRECISION = 4
+      private_constant :LEADING, :PRECISION
+
+      module_function
+
+      # @param value [Object] an attribute value, or lutaml's unset sentinel
+      # @return [Float, nil] the number it holds, or nil if it holds none
+      def read(value)
+        return nil if Escaping.blank?(value)
+        return value.to_f if value.is_a?(Numeric)
+
+        matched = value.to_s[LEADING]
+        matched&.to_f
+      end
+
+      # Finite only, but nothing here enforces it: Float#round(4) returns
+      # Infinity and NaN untouched rather than raising, so a non-finite value
+      # would be emitted verbatim as `Infinity`, which is not an SVG number.
+      # Every caller refuses a non-finite result before it gets here —
+      # Text#offset_x, Text#baseline_y, Element#composed_opacity and
+      # Arrowhead#triangle each fall back instead — because the fallback is a
+      # different value at each site and none of them is "emit nothing".
+      #
+      # @param value [Float] a computed, finite number
+      # @return [String] the attribute value to emit
+      def write(value)
+        value.round(PRECISION).to_s
+      end
+    end
+  end
+end

data/lib/etassia/svg/path.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "arrowhead"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Path element <path>
+    #
+    # Represents complex shapes and lines using SVG path data syntax.
+    # Commonly used for drawing edges in diagrams with curves and bend points.
+    class Path < Element
+      COMMAND_FORMATTERS = {
+        move: ->(command) { "M #{command[:x]} #{command[:y]}" },
+        line: ->(command) { "L #{command[:x]} #{command[:y]}" },
+        curve: lambda do |command|
+          "Q #{command[:cx]} #{command[:cy]} #{command[:x]} #{command[:y]}"
+        end,
+        bezier: lambda do |command|
+          controls = command.values_at(:c1x, :c1y, :c2x, :c2y).join(" ")
+          "C #{controls} #{command[:x]} #{command[:y]}"
+        end,
+        close: ->(_command) { "Z" },
+      }.freeze
+      private_constant :COMMAND_FORMATTERS
+
+      attribute :d, :string
+      attribute :stroke_dasharray, :string
+      attribute :stroke_linecap, :string
+      attribute :stroke_linejoin, :string
+      attribute :marker_end, :string
+      attribute :marker_start, :string
+
+      # Four renderers set `marker-end`; `marker-start` is settable directly
+      # too. Neither is emitted — Svg::Arrowhead draws them instead. See
+      # that class for why.
+      writes_attributes :d, :stroke_dasharray, :stroke_linecap, :stroke_linejoin
+
+      # Helper to build path data from move and line commands
+      #
+      # @param commands [Array<Hash>] Path commands
+      # @return [String] Path data string
+      def self.build_path_data(commands)
+        commands.map { |command| format_command(command) }.join(" ")
+      end
+
+      def self.format_command(command)
+        COMMAND_FORMATTERS[command[:type]]&.call(command)
+      end
+      private_class_method :format_command
+
+      protected
+
+      # The arrowheads this path asked for, drawn beside it.
+      #
+      # A head is a sibling shape rather than a child because `<path>` takes
+      # no drawable children. Each is a Polygon — a leaf that draws no
+      # siblings of its own — so one head is always one entry.
+      #
+      # @return [Array<String>] one entry of markup per arrowhead
+      def sibling_markup
+        Arrowhead.for(self).map(&:to_xml)
+      end
+    end
+  end
+end