stationery 0.1.0 → 0.3.0

data/lib/stationery/svg/document.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A parsed SVG drawn as vector paths on a canvas. Supports the subset icon
+    # sets use: path, rect (with rx), circle, ellipse, line, polyline, polygon
+    # and g, with fill, stroke, stroke width/caps/joins, fill-rule, opacity,
+    # inline styles, <style> stylesheets, transforms, linear/radial gradients
+    # and text/tspan. `currentColor` takes the colour you pass.
+    class Document
+      SHAPES = %w[path rect circle ellipse line polyline polygon].freeze
+      QUIET = (SHAPES + %w[svg g title desc metadata style defs linearGradient radialGradient stop text
+                           tspan]).freeze
+
+      def self.parse(source)
+        root = Parser.parse(source)
+        raise Error, "not an svg document" unless root&.name == "svg"
+
+        new(root)
+      end
+
+      attr_reader :view_box, :unsupported
+
+      def initialize(root)
+        @root = root
+        @view_box = read_view_box
+        @sheet = Stylesheet.parse(style_text)
+        @gradients = Gradient.collect(root, @sheet)
+        @unsupported = (element_names(root).uniq - QUIET).sort + approximations
+      end
+
+      def aspect = @view_box[2].to_f / @view_box[3]
+
+      # Scales the viewBox into the box (aspect ratio kept, centred). Text is
+      # drawn from `book` (bundled fonts when nil), unknown families in `family`.
+      def draw(canvas, x:, y:, width:, height:, color: "#000000", book: nil, family: nil)
+        vx, vy, vw, vh = @view_box
+        scale = [width.to_f / vw, height.to_f / vh].min
+        e = x + ((width - (vw * scale)) / 2.0) - (vx * scale)
+        f = y + ((height - (vh * scale)) / 2.0) - (vy * scale)
+        style = Style.new(Style::DEFAULTS, [scale, 0, 0, scale, e, f], color:, sheet: @sheet).child(@root)
+        painter = Painter.new(canvas, @gradients, @view_box.last(2))
+        text = Text.new(canvas, painter, book || Fonts::FontBook.new, family || Fonts::Bundled::DEFAULT)
+        shapes(@root, style) do |element, own|
+          element.name == "text" ? text.draw(element, own) : painter.paint(element, own)
+        end
+      end
+
+      private
+
+      def read_view_box
+        values = @root.attributes["viewBox"]&.split(/[\s,]+/)&.map { |v| number(v) }
+        return values if values&.size == 4
+
+        [0, 0, number(@root.attributes.fetch("width", "100")), number(@root.attributes.fetch("height", "100"))]
+      end
+
+      def style_text
+        styles = []
+        Parser.walk(@root) { |element| styles << element if element.name == "style" }
+        styles.flat_map(&:children).join(" ")
+      end
+
+      def element_names(element)
+        element.children.grep(Parser::Element).flat_map { |child| [child.name, *element_names(child)] }
+      end
+
+      def number(value)
+        float = value.to_s.to_f
+        float == float.round ? float.round : float
+      end
+
+      # Yields every drawn shape and text with its resolved style, in paint
+      # order, skipping undisplayed subtrees and hidden elements.
+      def shapes(parent, parent_style, &)
+        parent.children.each do |element|
+          style = parent_style.child(element)
+          next unless style.displayed?
+
+          if element.name == "g" then shapes(element, style, &)
+          elsif (SHAPES.include?(element.name) || element.name == "text") && style.visible? then yield element, style
+          end
+        end
+      end
+
+      # Paint references to missing gradients, gradient spreads drawn as pad
+      # and stylesheet selectors ignored.
+      def approximations
+        missing = []
+        shapes(@root, Style.new(sheet: @sheet).child(@root)) do |_element, style|
+          [style.fill, style.stroke].grep(Style::Reference).each do |reference|
+            missing << "url(##{reference.id})" unless @gradients.key?(reference.id)
+          end
+        end
+        spreads = @gradients.values.filter_map do |gradient|
+          "#{gradient.kind}Gradient spreadMethod=#{gradient.approximated_spread}" if gradient.approximated_spread
+        end
+        selectors = @sheet.unsupported.empty? ? [] : ["style selectors: #{@sheet.unsupported.join(", ")}"]
+        (missing + spreads).uniq.sort + selectors
+      end
+    end
+  end
+end

data/lib/stationery/svg/gradient.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A linearGradient or radialGradient paint server, with the stops and
+    # attributes it inherits through `href`. Coordinates are in gradient
+    # space; `matrix` maps them into the painted element's user space.
+    class Gradient
+      KINDS = %w[linearGradient radialGradient].freeze
+      INHERITED = %w[x1 y1 x2 y2 cx cy r fx fy gradientUnits gradientTransform spreadMethod].freeze
+      SPREADS = %w[reflect repeat].freeze
+
+      Stop = Data.define(:offset, :color, :opacity)
+
+      # Every gradient in the document, by id; stops take `sheet` rules.
+      def self.collect(root, sheet = Stylesheet::EMPTY)
+        elements = {}
+        Parser.walk(root) { |element| elements[element.attributes["id"]] = element if KINDS.include?(element.name) }
+        elements.delete(nil)
+        elements.transform_values { |element| new(element, elements, sheet) }
+      end
+
+      attr_reader :kind, :attributes, :stops
+
+      def initialize(element, elements, sheet = Stylesheet::EMPTY)
+        @sheet = sheet
+        @kind = element.name == "radialGradient" ? :radial : :linear
+        chain = lineage(element, elements)
+        @attributes = chain.reverse.map { |link| link.attributes.slice(*INHERITED) }.reduce({}, :merge)
+        @stops = read_stops(chain.find { |link| stop_elements(link).any? })
+      end
+
+      def bounding_box? = @attributes["gradientUnits"] != "userSpaceOnUse"
+
+      def approximated_spread
+        spread = @attributes["spreadMethod"]
+        spread if SPREADS.include?(spread)
+      end
+
+      # Gradient space to user space, for a shape whose box is [x, y, w, h].
+      def matrix(box)
+        own = Transform.parse(@attributes["gradientTransform"].to_s)
+        return own unless bounding_box?
+
+        x, y, w, h = box
+        Transform.multiply([w, 0, 0, h, x, y], own)
+      end
+
+      # Axial [x1 y1 x2 y2] or radial [fx fy 0 cx cy r] coordinates; user
+      # space percentages resolve against the viewport [width, height].
+      def coords(viewport)
+        width, height = viewport
+        if @kind == :linear
+          return [length("x1", 0, width), length("y1", 0, height), length("x2", "100%", width), length("y2", 0, height)]
+        end
+
+        cx = length("cx", "50%", width)
+        cy = length("cy", "50%", height)
+        [length("fx", cx, width), length("fy", cy, height), 0, cx, cy,
+         length("r", "50%", Math.sqrt(((width**2) + (height**2)) / 2.0))]
+      end
+
+      # The interpolated colour at `offset` as "#RRGGBB".
+      def color_at(offset, current)
+        before = @stops.reverse.find { |stop| stop.offset <= offset } || @stops.first
+        after = @stops.find { |stop| stop.offset >= offset } || @stops.last
+        span = after.offset - before.offset
+        t = span.positive? ? (offset - before.offset) / span : 0
+        from, to = [before, after].map { |stop| rgb(stop, current) }
+        "##{from.zip(to).map { |a, b| format("%02X", ((a + ((b - a) * t)) * 255).round) }.join}"
+      end
+
+      def rgb(stop, current) = Color.parse(Style.color(stop.color, current)).components
+
+      private
+
+      def lineage(element, elements)
+        chain = [element]
+        while (id = reference(chain.last)) && (parent = elements[id]) && !chain.include?(parent)
+          chain << parent
+        end
+        chain
+      end
+
+      def reference(element)
+        (element.attributes["href"] || element.attributes["xlink:href"]).to_s[/\A#(.+)/, 1]
+      end
+
+      def stop_elements(element)
+        element.children.select { |child| child.is_a?(Parser::Element) && child.name == "stop" }
+      end
+
+      def read_stops(element)
+        return [] unless element
+
+        floor = 0.0
+        stop_elements(element).map do |stop|
+          values = stop.attributes.merge(@sheet.declarations(stop), Style.declarations(stop.attributes["style"]))
+          floor = [floor, fraction(values.fetch("offset", "0")).clamp(0.0, 1.0)].max
+          Stop.new(floor, values.fetch("stop-color", "black"), values.fetch("stop-opacity", "1").to_f)
+        end
+      end
+
+      def length(key, default, reference)
+        value = @attributes.fetch(key, default)
+        return value.to_f if value.is_a?(Numeric)
+        return value.to_f unless value.strip.end_with?("%")
+
+        bounding_box? ? value.to_f / 100 : value.to_f * reference / 100
+      end
+
+      def fraction(value) = value.strip.end_with?("%") ? value.to_f / 100 : value.to_f
+    end
+  end
+end

data/lib/stationery/svg/painter.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Paints one shape element. Solid fills and strokes are one path; a
+    # gradient fill is a shading clipped to the shape, drawn under the
+    # stroke. A gradient stroke is drawn in the gradient's middle colour.
+    class Painter
+      def self.translucent(opacity) = opacity < 1 ? opacity : nil
+
+      def initialize(canvas, gradients, viewport)
+        @canvas = canvas
+        @gradients = gradients
+        @viewport = viewport
+      end
+
+      def paint(element, style)
+        fill = resolve(style.fill)
+        stroke = color(style.stroke, style)
+        if fill.is_a?(Gradient)
+          shade(element, style, fill)
+          fill = nil
+        end
+        return if fill.nil? && stroke.nil?
+
+        @canvas.path(fill:, stroke:, line_width: style.line_width, cap: style.cap || :butt, join: style.join || :miter,
+                     even_odd: style.even_odd?, opacity: Painter.translucent(style.opacity),
+                     transform: style.matrix) { |path| Shapes.trace(path, element) }
+      end
+
+      # A paint as one colour: a gradient's middle colour, nil for none.
+      def color(paint, style)
+        paint = resolve(paint)
+        paint.is_a?(Gradient) ? paint.color_at(0.5, style.color) : paint
+      end
+
+      private
+
+      def resolve(paint)
+        return paint unless paint.is_a?(Style::Reference)
+
+        gradient = @gradients[paint.id]
+        return paint.fallback unless gradient
+        return nil if gradient.stops.empty?
+
+        gradient
+      end
+
+      # Stops with differing opacities are approximated by the first one's.
+      def shade(element, style, gradient)
+        opacity = Painter.translucent(style.opacity * gradient.stops.first.opacity)
+        return single_stop(element, style, gradient, opacity) if gradient.stops.one?
+
+        box = Bounds.new.tap { |bounds| Shapes.trace(bounds, element) }.box
+        return if gradient.bounding_box? && box.nil?
+
+        shading = Shading.dictionary(gradient, gradient.coords(@viewport), style.color)
+        matrix = Transform.multiply(style.matrix, gradient.matrix(box))
+        @canvas.shade(shading, matrix:, transform: style.matrix, even_odd: style.even_odd?, opacity:) do |path|
+          Shapes.trace(path, element)
+        end
+      end
+
+      def single_stop(element, style, gradient, opacity)
+        @canvas.path(fill: gradient.color_at(0, style.color), even_odd: style.even_odd?, opacity:,
+                     transform: style.matrix) { |path| Shapes.trace(path, element) }
+      end
+    end
+  end
+end

data/lib/stationery/svg/parser.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Stationery
+  module SVG
+    # A minimal XML reader for SVG documents: elements, attributes and nesting.
+    # Comments, processing instructions and doctypes are skipped; text content
+    # (CDATA included) is kept only inside text, tspan and style, as String
+    # children with entities decoded and each whitespace run one space.
+    module Parser
+      Element = Data.define(:name, :attributes, :children)
+
+      TEXT = %w[text tspan style].freeze
+
+      IGNORED = /<!--.*?-->|<\?.*?\?>|<!DOCTYPE[^>]*>/m
+      CDATA = /<!\[CDATA\[(.*?)\]\]>/m
+      ESCAPES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;" }.freeze
+      TAG = %r{<(/?)([a-zA-Z][\w:.-]*)((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(/?)>}m
+      ATTRIBUTE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/
+
+      module_function
+
+      def parse(source)
+        source = source.to_s.gsub(IGNORED, "").gsub(CDATA) { Regexp.last_match(1).gsub(/[&<>]/, ESCAPES) }
+        scanner = StringScanner.new(source)
+        root = Element.new("document", {}, [])
+        stack = [root]
+        while (content = scanner.scan_until(/(?=<)/))
+          keep(stack.last, content)
+          tag = scanner.scan(TAG) or (scanner.getch && next)
+          handle(stack, *tag.match(TAG).captures)
+        end
+        root.children.first
+      end
+
+      # Yields the element and every element below it, depth first.
+      def walk(element, &)
+        yield element
+        element.children.each { |child| walk(child, &) if child.is_a?(Element) }
+      end
+
+      def keep(element, content)
+        return if content.empty? || !TEXT.include?(element.name)
+
+        element.children << Stationery::Text::Entities.decode(content).gsub(/\s+/, " ")
+      end
+
+      def handle(stack, closing, name, attributes, self_closing)
+        return stack.pop if closing == "/" && stack.size > 1
+
+        element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
+        stack.last.children << element
+        stack << element if self_closing.empty?
+      end
+    end
+  end
+end

data/lib/stationery/svg/path_data.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Stationery
+  module SVG
+    class Error < Stationery::Error; end
+
+    # Parses SVG path data into absolute segments:
+    #
+    #   [:move, x, y] [:line, x, y] [:curve, x1, y1, x2, y2, x, y] [:close]
+    #
+    # Quadratic curves become cubics and elliptical arcs become cubic segments
+    # of at most 90 degrees, so a drawing backend needs only move, line, curve
+    # and close.
+    class PathData
+      ARITY = { "M" => 2, "L" => 2, "T" => 2, "H" => 1, "V" => 1, "C" => 6, "S" => 4, "Q" => 4, "A" => 7,
+                "Z" => 0 }.freeze
+      NUMBER = /[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/
+      FLAG = /[01]/
+      SEPARATORS = /[\s,]*/
+
+      def self.parse(data) = new(data).segments
+
+      def initialize(data)
+        @scanner = StringScanner.new(data.to_s)
+        @segments = []
+        @x = @y = @start_x = @start_y = 0
+        @control = nil
+        @command = nil
+      end
+
+      def segments
+        loop do
+          @scanner.skip(SEPARATORS)
+          break if @scanner.eos?
+
+          if (letter = @scanner.scan(/[MmLlHhVvCcSsQqTtAaZz]/))
+            @command = letter
+            next close_path if letter.upcase == "Z"
+          end
+          raise Error, "unreadable path data near #{@scanner.rest[0, 12].inspect}" unless @command
+
+          apply(@command, arguments(@command))
+        end
+        @segments
+      end
+
+      private
+
+      def arguments(command)
+        Array.new(ARITY.fetch(command.upcase)) do |index|
+          @scanner.skip(SEPARATORS)
+          token = @scanner.scan(command.upcase == "A" && [3, 4].include?(index) ? FLAG : NUMBER)
+          raise Error, "unreadable path data near #{@scanner.rest[0, 12].inspect}" unless token
+
+          number(token)
+        end
+      end
+
+      def number(token)
+        token.match?(/[.eE]/) ? token.to_f : token.to_i
+      end
+
+      def apply(command, args)
+        relative = command == command.downcase
+        case command.upcase
+        when "M" then move(*absolute(args, relative))
+        when "L" then line(*absolute(args, relative))
+        when "H" then line(relative ? @x + args[0] : args[0], @y)
+        when "V" then line(@x, relative ? @y + args[0] : args[0])
+        when "C" then curve(*absolute(args, relative))
+        when "S" then curve(*reflected_control, *absolute(args, relative))
+        when "Q" then quadratic(*absolute(args, relative))
+        when "T" then quadratic(*reflected_control, *absolute(args, relative))
+        else arc(*args.first(5), *absolute(args.last(2), relative))
+        end
+      end
+
+      def absolute(args, relative)
+        return args unless relative
+
+        args.each_with_index.map { |value, index| value + (index.even? ? @x : @y) }
+      end
+
+      def move(x, y)
+        @segments << [:move, x, y]
+        @x = @start_x = x
+        @y = @start_y = y
+        @control = nil
+        # Coordinates after a move are implicit lines.
+        @command = @command == "m" ? "l" : "L"
+      end
+
+      def line(x, y)
+        @segments << [:line, x, y]
+        @x = x
+        @y = y
+        @control = nil
+      end
+
+      def curve(x1, y1, x2, y2, x, y)
+        @segments << [:curve, x1, y1, x2, y2, x, y]
+        @x = x
+        @y = y
+        @control = [x2, y2]
+      end
+
+      def quadratic(qx, qy, x, y)
+        curve(@x + ((2 * (qx - @x)) / 3.0), @y + ((2 * (qy - @y)) / 3.0),
+              x + ((2 * (qx - x)) / 3.0), y + ((2 * (qy - y)) / 3.0), x, y)
+        @control = [qx, qy]
+      end
+
+      def reflected_control
+        return [@x, @y] unless @control
+
+        [(2 * @x) - @control[0], (2 * @y) - @control[1]]
+      end
+
+      def close_path
+        @segments << [:close]
+        @x = @start_x
+        @y = @start_y
+        @control = nil
+      end
+
+      def arc(rx, ry, rotation, large, sweep, x, y)
+        return line(x, y) if rx.zero? || ry.zero?
+
+        Arc.new(@x, @y, rx.abs, ry.abs, rotation, large, sweep, x, y).curves.each { |c| curve(*c) }
+        @x = x
+        @y = y
+      end
+    end
+  end
+end

data/lib/stationery/svg/selector.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A compound CSS selector: an element name or `*`, then any number of
+    # `.class` and `#id` parts. Combinators, pseudo-classes and attribute
+    # selectors are not read.
+    class Selector
+      PATTERN = /\A(\*|[a-zA-Z][\w-]*)?((?:[.#][\w-]+)*)\z/
+
+      def self.parse(text)
+        match = text.match(PATTERN)
+        return nil if match.nil? || text.empty?
+
+        parts = match[2].scan(/[.#][\w-]+/)
+        new(match[1], parts.grep(/\A#/).map { |id| id[1..] }, parts.grep(/\A\./).map { |name| name[1..] })
+      end
+
+      def initialize(name, ids, classes)
+        @name = name == "*" ? nil : name
+        @ids = ids
+        @classes = classes
+      end
+
+      # [ids, classes, element names], compared in that order.
+      def specificity = [@ids.size, @classes.size, @name ? 1 : 0]
+
+      def match?(element)
+        attributes = element.attributes
+        return false if @name && @name != element.name
+        return false unless @ids.all?(attributes["id"])
+
+        (@classes - attributes["class"].to_s.split).empty?
+      end
+    end
+  end
+end

data/lib/stationery/svg/shading.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A gradient as a PDF shading dictionary: axial (type 2) or radial
+    # (type 3) in DeviceRGB, its stops as one exponential function or a
+    # stitching of one per pair. The ends always extend (spread `pad`).
+    module Shading
+      module_function
+
+      def dictionary(gradient, coords, current)
+        {
+          ShadingType: gradient.kind == :radial ? 3 : 2, ColorSpace: :DeviceRGB, Coords: coords,
+          Function: function(padded(gradient.stops), gradient, current), Extend: [true, true]
+        }
+      end
+
+      def function(stops, gradient, current)
+        colors = stops.map { |stop| gradient.rgb(stop, current).map { |v| v.round(4) } }
+        segments = colors.each_cons(2).map { |c0, c1| { FunctionType: 2, Domain: [0, 1], C0: c0, C1: c1, N: 1 } }
+        return segments.first if segments.one?
+
+        { FunctionType: 3, Domain: [0, 1], Functions: segments, Bounds: stops[1..-2].map(&:offset),
+          Encode: [0, 1] * segments.size }
+      end
+
+      def padded(stops)
+        stops = [stops.first.with(offset: 0.0), *stops] if stops.first.offset.positive?
+        stops = [*stops, stops.last.with(offset: 1.0)] if stops.last.offset < 1
+        stops
+      end
+    end
+  end
+end

data/lib/stationery/svg/shapes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Traces one SVG shape element onto a canvas path.
+    module Shapes
+      module_function
+
+      def trace(path, element)
+        a = element.attributes
+        case element.name
+        when "path" then trace_data(path, PathData.parse(a["d"]))
+        when "rect" then path.rounded_rect(f(a, "x"), f(a, "y"), f(a, "width"), f(a, "height"), f(a, "rx", f(a, "ry")))
+        when "circle" then path.ellipse(f(a, "cx"), f(a, "cy"), f(a, "r"), f(a, "r"))
+        when "ellipse" then path.ellipse(f(a, "cx"), f(a, "cy"), f(a, "rx"), f(a, "ry"))
+        when "line" then trace_points(path, [[f(a, "x1"), f(a, "y1")], [f(a, "x2"), f(a, "y2")]], close: false)
+        else trace_points(path, points(a["points"]), close: element.name == "polygon")
+        end
+      end
+
+      def trace_data(path, segments)
+        segments.each do |kind, *args|
+          case kind
+          when :move then path.move_to(*args)
+          when :line then path.line_to(*args)
+          when :curve then path.curve_to(*args)
+          else path.close
+          end
+        end
+      end
+
+      def trace_points(path, points, close:)
+        return if points.empty?
+
+        path.move_to(*points.first)
+        points.drop(1).each { |point| path.line_to(*point) }
+        path.close if close
+      end
+
+      def points(source)
+        source.to_s.scan(PathData::NUMBER).map { |v| v.match?(/[.eE]/) ? v.to_f : v.to_i }.each_slice(2)
+              .select { |pair| pair.size == 2 }
+      end
+
+      def f(attributes, key, default = 0)
+        value = attributes[key]
+        return default if value.nil? || value.empty?
+
+        number = value.to_f
+        number == number.round ? number.round : number
+      end
+    end
+  end
+end