etassia 0.1.0

data/lib/etassia/svg/path_geometry.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "../js_math"
+
+module Etassia
+  module Svg
+    # Where a path starts and ends, and which way it is travelling there.
+    # Only the two ends matter (for drawing an arrowhead), so this walks
+    # commands for the current point and never builds the curves.
+    #
+    # An arc's chord is not its tangent, so it yields NO heading rather
+    # than guessing wrong -- don't add arc tangents without the centre
+    # parameterisation.
+    #
+    # An unrecognised byte is skipped and following numbers are read as
+    # more arguments for the command in force -- deliberate leniency,
+    # reachable only by a caller assigning a hand-built `d` string
+    # directly (Path.from_xml no longer exists as a way in).
+    class PathGeometry
+      # One anchor: a point on the path and the unit direction of travel
+      # through it.
+      Anchor = Struct.new(:x, :y, :dx, :dy)
+
+      # Command letter to the number of numbers it consumes. Repeated
+      # argument groups are the SVG rule, so `L 1 2 3 4` is two segments.
+      ARITY = {
+        "m" => 2, "l" => 2, "h" => 1, "v" => 1, "c" => 6,
+        "s" => 4, "q" => 4, "t" => 2, "a" => 7, "z" => 0
+      }.freeze
+      private_constant :ARITY
+
+      TOKEN = /([MmLlHhVvCcSsQqTtAaZz])|
+               ([-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)/x
+      private_constant :TOKEN
+
+      # Arc flags are single digits even when no separator follows, so they
+      # cannot use the generic number scan at their two argument positions.
+      ARC_FLAG_TOKEN = /([MmLlHhVvCcSsQqTtAaZz])|([01])/
+      private_constant :ARC_FLAG_TOKEN
+
+      # A move followed by more coordinates draws lines: only the first
+      # group of `M 1 2 3 4` is a move. Every other command simply repeats.
+      AFTER_FIRST = { "M" => "L", "m" => "l" }.freeze
+      REFERENCE_BUILDERS = {
+        "l" => :line_references,
+        "h" => :horizontal_references,
+        "v" => :vertical_references,
+        "c" => :cubic_references,
+        "s" => :smooth_cubic_references,
+        "q" => :quadratic_references,
+        "t" => :smooth_quadratic_references,
+      }.freeze
+      private_constant :AFTER_FIRST, :REFERENCE_BUILDERS
+
+      # @param data [String, nil] the `d` attribute
+      def initialize(data)
+        @point = [0.0, 0.0]
+        @subpath_start = @point
+        @origin = nil
+        @terminus = nil
+        @origin_direction = nil
+        @recent_direction = nil
+        @quadratic_control = nil
+        @cubic_control = nil
+        walk(data.to_s)
+      end
+
+      # @return [Anchor, nil] the first point, pointing along the first segment
+      def origin
+        # `false` means a command that anchors nothing came first, so the
+        # segment after it must not be promoted to the start of the path.
+        return nil unless @origin
+
+        start, reference = @origin
+        heading(start, start, reference) ||
+          (@origin_direction && heading(start, *@origin_direction))
+      end
+
+      # @return [Anchor, nil] the last point, pointing along the last segment
+      def terminus
+        return nil unless @terminus
+
+        reference, finish = @terminus
+        heading(finish, reference, finish) ||
+          (@recent_direction && heading(finish, *@recent_direction))
+      end
+
+      private
+
+      def walk(data)
+        each_command(data) { |letter, args| apply(letter, args) }
+      end
+
+      # Yields one command letter and one full argument group at a time,
+      # repeating the letter while arguments remain. A bare `M` with four
+      # numbers draws a line after the move, which is the SVG rule and the
+      # reason this cannot just split on letters.
+      def each_command(data, &)
+        letter = nil
+        numbers = []
+        scanner = StringScanner.new(data)
+        while scan_token(scanner, letter, numbers)
+          letter, numbers = consume_token(scanner, letter, numbers, &)
+        end
+        flush(letter, numbers, &)
+      end
+
+      # An invalid byte sequence makes the scan regex itself raise rather
+      # than simply fail to match. Stop as a genuine non-match would instead
+      # of letting a foreign document's garbage encoding escape raw.
+      def scan_token(scanner, letter, numbers)
+        token = arc_flag_position?(letter, numbers) ? ARC_FLAG_TOKEN : TOKEN
+        scanner.scan_until(token)
+      rescue ArgumentError
+        nil
+      end
+
+      def consume_token(scanner, letter, numbers, &)
+        command = scanner[1]
+        return append_number(scanner[2], letter, numbers) unless command
+
+        flush(letter, numbers, &)
+        [command, []]
+      end
+
+      def append_number(number, letter, numbers)
+        numbers << number.to_f
+        [letter, numbers]
+      end
+
+      def arc_flag_position?(letter, numbers)
+        return false unless letter&.downcase == "a"
+
+        (numbers.length % ARITY.fetch("a")).between?(3, 4)
+      end
+
+      # A group with too few numbers is dropped, and the walk carries on with
+      # the next command. An arrowhead placed off a half-read command would
+      # be worse than none. A conformant renderer is stricter still — it
+      # abandons the whole path from the first error — but Etassia never emits
+      # malformed data, and reading the rest costs nothing.
+      def flush(letter, numbers)
+        return if letter.nil?
+
+        size = ARITY.fetch(letter.downcase)
+        return yield(letter, []) if size.zero?
+
+        numbers.each_slice(size).with_index do |group, index|
+          break if group.size < size
+
+          yield(index.zero? ? letter : AFTER_FIRST.fetch(letter, letter), group)
+        end
+      end
+
+      def apply(letter, args)
+        lower = letter.downcase
+        args = relative(letter, lower, args)
+        clear_unrelated_control(lower)
+        return move(args) if lower == "m"
+        return close if lower == "z"
+        return arc(args) if lower == "a"
+
+        segment(*references(lower, args))
+      end
+
+      # Smooth commands may only reflect a control from the same curve
+      # family immediately before them; retaining either control through a
+      # different command would bend a later shorthand curve unexpectedly.
+      def clear_unrelated_control(lower)
+        case lower
+        when "q", "t" then @cubic_control = nil
+        when "c", "s" then @quadratic_control = nil
+        else
+          @quadratic_control = nil
+          @cubic_control = nil
+        end
+      end
+
+      # SVG gives an arc two degenerate forms, and they are not the same
+      # thing. An arc whose endpoints coincide is omitted entirely, so it must
+      # not disturb the anchors either: the segment before it is still the end
+      # of the path and the segment after it is still the start. Only the
+      # zero-radius form becomes a straight line. Handling one and not the
+      # other silently dropped the arrowhead off
+      # `M 0 0 L 10 0 A 5 5 0 0 1 10 0`.
+      #
+      # Exact equality, because a relative endpoint of `0 0` is computed as
+      # `@point + 0.0` and lands on the current point exactly.
+      def arc(args)
+        end_point = [args[5], args[6]]
+        return if end_point == @point
+        return segment(*straight(end_point)) if args[0].zero? || args[1].zero?
+
+        traverse(end_point)
+      end
+
+      # Moves the current point along a segment that offers no usable
+      # tangent. The point has to advance or every command after it lands in
+      # the wrong place, but neither end of an arc may anchor an arrowhead.
+      #
+      # A break in continuity before a pending origin gains a usable direction
+      # closes the question rather than letting a later segment supply that
+      # direction. An arc always breaks it because the path starts on that
+      # unanchorable segment. A later move breaks it only after a zero-length
+      # segment has recorded an origin; moves alone leave the question open for
+      # the first real segment.
+      def traverse(end_point)
+        @origin = false if @origin_direction.nil?
+        @terminus = nil
+        @recent_direction = nil
+        @point = end_point
+      end
+
+      # The segment a command draws, as [outgoing reference, incoming
+      # reference, end point]. A straight segment is its own tangent, so both
+      # references are the far end of it; a curve takes the control point
+      # nearest each end.
+      #
+      # Smooth curves reflect the preceding control in absolute space so
+      # relative and absolute commands follow the same geometry. An arc gives
+      # no references at all — see the note on the class.
+      def references(lower, args)
+        send(REFERENCE_BUILDERS.fetch(lower), args)
+      end
+
+      def line_references(args)
+        straight(args.values_at(0, 1))
+      end
+
+      def horizontal_references(args)
+        straight([args[0], @point[1]])
+      end
+
+      def vertical_references(args)
+        straight([@point[0], args[0]])
+      end
+
+      def cubic_references(args)
+        @cubic_control = args.values_at(2, 3)
+        [args.values_at(0, 1), @cubic_control, args.values_at(4, 5)]
+      end
+
+      def smooth_cubic_references(args)
+        outgoing = reflection(@cubic_control)
+        @cubic_control = args.values_at(0, 1)
+        [outgoing, @cubic_control, args.values_at(2, 3)]
+      end
+
+      def quadratic_references(args)
+        @quadratic_control = args.values_at(0, 1)
+        [@quadratic_control, @quadratic_control, args.values_at(2, 3)]
+      end
+
+      # ARITY and TOKEN admit no other reference-bearing command here.
+      def smooth_quadratic_references(args)
+        @quadratic_control = reflection(@quadratic_control)
+        [@quadratic_control, @quadratic_control, args.values_at(0, 1)]
+      end
+
+      # Reflecting a control point through the current point. Written as
+      # `point + (point - source)` rather than `2 * point - source`, which is
+      # the same number but overflows on the way: at `M 1e308 0 S …` the
+      # source IS the current point, so the reflection is that point, and
+      # doubling it reached Infinity and pointed the head backwards.
+      def reflection(control)
+        source = control || @point
+        @point.zip(source).map { |point, original| point + (point - original) }
+      end
+
+      def straight(destination)
+        [destination, @point, destination]
+      end
+
+      # Relative commands offset from the current point. On an arc only the
+      # final coordinate pair is a point; the radii and flags are not.
+      def relative(letter, lower, args)
+        return args if letter == letter.upcase
+
+        case lower
+        when "h" then offset_coordinate(args, 0)
+        when "v" then offset_coordinate(args, 1)
+        when "a" then relative_arc(args)
+        else relative_points(args)
+        end
+      end
+
+      def offset_coordinate(args, axis)
+        [args[0] + @point[axis]]
+      end
+
+      def relative_arc(args)
+        args[0, 5] + relative_points(args.drop(5))
+      end
+
+      def relative_points(args)
+        args.each_slice(2).flat_map do |x, y|
+          [x + @point[0], y + @point[1]]
+        end
+      end
+
+      def move(args)
+        @origin = false if @origin && @origin_direction.nil?
+        @point = [args[0], args[1]]
+        @subpath_start = @point
+        @terminus = nil
+        @recent_direction = nil
+      end
+
+      def close
+        segment(@subpath_start, @point, @subpath_start)
+      end
+
+      def segment(out_reference, in_reference, end_point)
+        @origin = [@point, out_reference] if @origin.nil?
+        remember_directions(@point, out_reference, in_reference, end_point)
+        @terminus = [in_reference, end_point]
+        @point = end_point
+      end
+
+      # Degenerate endpoint derivatives still have a direction when another
+      # edge of the same control polygon, or an earlier segment, establishes
+      # one. Keeping the pair instead of an anchor lets the true endpoint be
+      # supplied only when the caller asks for it. For a straight segment the
+      # middle pair is reversed, but the first and third pairs are the same,
+      # so the reversed one can never be `directions.first` or
+      # `directions.last`.
+      def remember_directions(*points)
+        directions = points.each_cons(2).select do |from, to|
+          heading(to, from, to)
+        end
+        return if directions.empty?
+
+        @origin_direction ||= directions.first
+        @recent_direction = directions.last
+      end
+
+      # Where the anchor sits is not where its direction comes from: the last
+      # point heads AWAY from the control point behind it, while the first
+      # heads TOWARDS the one in front. Both are the direction of travel, so
+      # both are read from the same pair, and the point is passed separately
+      # rather than assumed to be one end of it.
+      #
+      # @param at [Array] the point the anchor sits on
+      # @param from [Array] the tail of the direction of travel
+      # @param to [Array] the head of the direction of travel
+      # @return [Anchor, nil] nil when the two coincide, which leaves no
+      #   direction to point an arrowhead along
+      def heading(at, from, to)
+        dx, dy = direction(from, to)
+        length = JsMath.hypot(dx, dy)
+        return nil unless usable_heading?(at, length)
+
+        Anchor.new(at[0], at[1], dx / length, dy / length)
+      end
+
+      def direction(from, to)
+        delta = to.zip(from).map { |finish, start| finish - start }
+        return delta if delta.all?(&:finite?)
+
+        # Two finite coordinates can still overflow the distance between them:
+        # `M -1e308 0 L 1e308 0` is 2e308 apart. A direction does not change
+        # with scale, so halving both ends brings the difference back into
+        # range and answers the same question. Only reached on overflow, so
+        # nothing else loses precision to it.
+        to.zip(from).map { |finish, start| (finish / 2) - (start / 2) }
+      end
+
+      def usable_heading?(at, length)
+        # Not merely non-zero: path data carrying an out-of-range exponent
+        # can put Infinity in the anchor or in a coordinate delta. The guard
+        # keeps Infinity/Infinity out of the heading and a non-finite anchor
+        # out of the polygon's points.
+        at.all?(&:finite?) && length.finite? && length.positive?
+      end
+    end
+  end
+end

data/lib/etassia/svg/polygon.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Polygon element <polygon>
+    #
+    # Represents a closed shape defined by a series of points.
+    class Polygon < Element
+      attribute :points, :string
+
+      writes_attributes :points
+
+      # Helper to build points string from coordinates array
+      #
+      # @param coords [Array<Array>] Array of [x, y] coordinates
+      # @return [String] Points string for polygon
+      def self.build_points(coords)
+        coords.map { |x, y| "#{x},#{y}" }.join(" ")
+      end
+    end
+  end
+end

data/lib/etassia/svg/polyline.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Polyline element <polyline>
+    #
+    # Represents an open shape defined by a series of connected points.
+    class Polyline < Element
+      attribute :points, :string
+
+      # Emitted nothing before this: a Polyline rendered as
+      # `<polyline stroke="blue"/>` with no points, and
+      # renderer/xy_chart.rb:337 draws line series with it.
+      writes_attributes :points
+
+      # Helper to build points string from coordinates array
+      #
+      # @param coords [Array<Array>] Array of [x, y] coordinates
+      # @return [String] Points string for polyline
+      def self.build_points(coords)
+        coords.map { |x, y| "#{x},#{y}" }.join(" ")
+      end
+    end
+  end
+end

data/lib/etassia/svg/rect.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+
+module Etassia
+  module Svg
+    # SVG Rectangle element <rect>
+    #
+    # Represents a rectangle shape with position, dimensions, and optional
+    # rounded corners.
+    class Rect < Element
+      attribute :x, :float
+      attribute :y, :float
+      attribute :width, :float
+      attribute :height, :float
+      attribute :rx, :float
+      attribute :ry, :float
+      attribute :stroke_dasharray, :string
+      attribute :fill_opacity, :string
+
+      # fill-opacity is NOT listed here. Element already emits it for every
+      # element, and listing it again produced
+      # `fill-opacity="0.5" fill-opacity="0.5"` — the last 5 malformed cases
+      # in the corpus.
+      #
+      # The attribute declaration above stays so `fill_opacity=` is still a
+      # settable Ruby accessor -- from_xml no longer works on Rect at all
+      # (Lutaml::Model::TypeOnlyMappingError, no `root` declared). It still
+      # re-emits through Element exactly once, whichever way it was set.
+      writes_attributes :x, :y, :width, :height, :rx, :ry, :stroke_dasharray
+    end
+  end
+end

data/lib/etassia/svg/style.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Etassia
+  module Svg
+    # Represents CSS styling for SVG elements
+    #
+    # Encapsulates style properties that can be applied to SVG elements
+    # as inline styles or style attributes.
+    class Style < Lutaml::Model::Serializable
+      attribute :fill, :string
+      attribute :stroke, :string
+      attribute :stroke_width, :float
+      attribute :stroke_dasharray, :string
+      attribute :opacity, :float
+      attribute :fill_opacity, :float
+      attribute :stroke_opacity, :float
+      attribute :font_family, :string
+      attribute :font_size, :float
+      attribute :font_weight, :string
+      attribute :text_anchor, :string
+
+      CSS_PROPERTIES = {
+        fill: "fill",
+        stroke: "stroke",
+        stroke_width: "stroke-width",
+        stroke_dasharray: "stroke-dasharray",
+        opacity: "opacity",
+        fill_opacity: "fill-opacity",
+        stroke_opacity: "stroke-opacity",
+        font_family: "font-family",
+        font_size: "font-size",
+        font_weight: "font-weight",
+        text_anchor: "text-anchor",
+      }.freeze
+      private_constant :CSS_PROPERTIES
+
+      # Convert style to CSS string for inline style attribute
+      #
+      # @return [String] CSS style string
+      def to_css
+        CSS_PROPERTIES.filter_map do |attribute, property|
+          value = public_send(attribute)
+          "#{property}:#{value}" if value
+        end.join(";")
+      end
+    end
+  end
+end

data/lib/etassia/svg/text.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "element"
+require_relative "numbers"
+require_relative "tspan"
+
+module Etassia
+  module Svg
+    # SVG Text element <text>
+    #
+    # Displays text content at specified coordinates with optional styling
+    # and anchoring. Used for labels, annotations, and textual content.
+    class Text < Element
+      attribute :x, :float
+      attribute :y, :float
+      attribute :dx, :float
+      attribute :dy, :float
+      attribute :text_anchor, :string
+      attribute :font_family, :string
+      attribute :font_size, :string
+      attribute :font_weight, :string
+      attribute :font_style, :string
+      attribute :text_decoration, :string
+      # `textLength` and `lengthAdjust`: the width the text must fill, so a
+      # viewer's font cannot move what follows it.
+      attribute :text_length, :float
+      attribute :length_adjust, :string
+      attribute :dominant_baseline, :string
+      attribute :content, :string, collection: true
+      attribute :tspans, Tspan, collection: true
+      # "preserve" keeps the spaces at the edges of tspan runs.
+      attribute :xml_space, :string
+
+      # How far below `y` the baseline sits, in ems -- stands in for
+      # `dominant-baseline` (rejected under :metanorma). Conventional
+      # approximations, NOT font metrics: `central` is deliberately
+      # collapsed onto `middle` since Etassia has none. An unnamed value
+      # stays on the alphabetic baseline (deliberate for `mathematical`).
+      #
+      # Needs a unitless font size in user units; a relative size from
+      # a foreign document (`2em`) has no parent to resolve against and
+      # reads as the bare number.
+      BASELINE_SHIFTS = {
+        "middle" => 0.35,
+        "central" => 0.35,
+        "hanging" => 0.8,
+        "text-before-edge" => 0.8,
+        "text-after-edge" => -0.2,
+        "ideographic" => -0.2,
+      }.freeze
+
+      # The CSS initial font-size, used when a Text carries a baseline
+      # request but no size of its own. Every renderer sets one; this keeps
+      # a hand-built element from shifting by an arbitrary amount.
+      DEFAULT_FONT_SIZE = 16.0
+
+      # One line of a multi-line label, in ems (the former `dy="1.2em"`).
+      LINE_HEIGHT_EMS = 1.2
+      private_constant :BASELINE_SHIFTS, :DEFAULT_FONT_SIZE, :LINE_HEIGHT_EMS
+
+      # `dx` and `dy` are folded into x/y rather than emitted, never written
+      # out directly.
+      #
+      # Written out rather than declared with .writes_attributes, because
+      # `x` and `y` are emitted from computed readers — see #offset_x and
+      # #baseline_y.
+      ATTRIBUTE_PAIRS = [
+        ["x", :offset_x],
+        ["y", :baseline_y],
+        ["text-anchor", :text_anchor],
+        ["font-family", :font_family],
+        ["font-size", :font_size],
+        ["font-weight", :font_weight],
+        ["font-style", :font_style],
+        ["text-decoration", :text_decoration],
+        ["textLength", :text_length],
+        ["lengthAdjust", :length_adjust],
+        ["xml:space", :xml_space],
+      ].map(&:freeze).freeze
+      private_constant :ATTRIBUTE_PAIRS
+
+      protected
+
+      # A text element carries content, so it is not the self-closing tag
+      # the base class writes.
+      #
+      # `content` is declared `collection: true`. Renderers assign a plain
+      # String, so join rather than interpolate — Array(content).join is a
+      # no-op for a plain string and correct if content is ever multi-valued.
+      # Content may hold newlines, so this is the one entry in #xml_lines
+      # that is not a single line. It is why Group indents entries rather
+      # than lines.
+      #
+      # Every renderer call site sets exactly one of `content`/`tspans`.
+      #
+      # @return [String] XML string
+      def element_markup
+        "<text#{build_attributes}>#{body}</text>"
+      end
+
+      def element_attributes
+        attribute_pairs(ATTRIBUTE_PAIRS)
+      end
+
+      # SVG dx/dy are per-glyph offset lists. Their :float declarations make
+      # lutaml keep only the leading number before this method sees the value.
+      def offset_x
+        offset = Numbers.read(dx)
+        return x if offset.nil?
+
+        computed_x = (Numbers.read(x) || 0.0) + offset
+        return x unless computed_x.finite?
+
+        Numbers.write(computed_x)
+      end
+
+      # `y` with the baseline request folded in.
+      #
+      # Returns the reader untouched when there is no shift, so a Text that
+      # never asked for one serialises exactly as it did before. It is also
+      # the only usable fallback when the computed coordinate overflows.
+      #
+      # @return [Object, nil] the y attribute value
+      def baseline_y
+        shift = baseline_shift
+        offset = Numbers.read(dy)
+        return y if shift.zero? && offset.nil?
+
+        computed_y = (Numbers.read(y) || 0.0) + (offset || 0.0) + shift
+        return y unless computed_y.finite?
+
+        Numbers.write(computed_y)
+      end
+
+      private
+
+      # Every renderer call site sets exactly one of `content`/`tspans`.
+      #
+      # @return [String]
+      def body
+        place_lines
+        escaped_content = Escaping.escape_text(Array(content).join)
+        escaped_content + Array(tspans).map(&:to_xml).join
+      end
+
+      # Gives each run that starts a new line an absolute `y`: this text's
+      # baseline plus the lines accumulated so far. Idempotent, so repeated
+      # serialisation writes the same values.
+      def place_lines
+        lines = 0
+        Array(tspans).each do |run|
+          next unless run.line_shift
+
+          lines += run.line_shift
+          run.y = line_y(lines)
+        end
+      end
+
+      def line_y(lines)
+        size = Numbers.read(font_size) || DEFAULT_FONT_SIZE
+        base = Numbers.read(baseline_y) || 0.0
+        placed = base + (lines * LINE_HEIGHT_EMS * size)
+        placed.finite? ? placed.round(4) : nil
+      end
+
+      # May be non-finite when the font size is: #baseline_y is the one place
+      # that can fall back, so the check lives there rather than here too.
+      #
+      # @return [Float] the baseline offset in user units
+      def baseline_shift
+        return 0.0 if Escaping.blank?(dominant_baseline)
+
+        ems = BASELINE_SHIFTS.fetch(dominant_baseline.to_s.strip.downcase, 0.0)
+        return 0.0 if ems.zero?
+
+        ems * (Numbers.read(font_size) || DEFAULT_FONT_SIZE)
+      end
+    end
+  end
+end