sevgi-graphics 0.73.2 → 0.93.1

data/lib/sevgi/graphics/mixtures/rdf.rb

@@ -3,39 +3,68 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for RDF and license metadata.
       module RDF
+        # Adds RDF license metadata inside a metadata element.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License(**kwargs, &block) = metadata { RDFWork(**kwargs, &block) }
 
         # Use SPDX license codes in underscored form: https://spdx.org/licenses/
         #
+        # Adds Creative Commons BY-SA license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-sa/4.0/", &block)
         end
 
+        # Adds Creative Commons BY-NC license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc/4.0/", &block)
         end
 
+        # Adds Creative Commons BY-NC-SA license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_SA(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-sa/4.0/", &block)
         end
 
+        # Adds Creative Commons BY-ND license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nd/4.0/", &block)
         end
 
+        # Adds Creative Commons BY-NC-ND license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC_BY_NC_ND(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/licenses/by-nc-nd/4.0/", &block)
         end
 
+        # Adds Creative Commons Zero metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_CC0(**kwargs, &block)
           License(**kwargs, license: "https://creativecommons.org/publicdomain/zero/1.0/", &block)
         end
 
+        # Adds Free Art License metadata.
+        # @param kwargs [Hash] RDF work options
+        # @return [Sevgi::Graphics::Element] metadata element
         def License_LAL(**kwargs, &block) = License(**kwargs, license: "https://artlibre.org/licence/lal/en/", &block)
 
+        # Builds an RDF root element.
+        # @param _kwargs [Hash] currently unused options
+        # @return [Sevgi::Graphics::Element] RDF element
+        # @raise [Sevgi::ArgumentError] when no block is given
         def RDF(**_kwargs, &block)
-          raise ArgumentError, "Block required" unless block
+          ArgumentError.("Block required") unless block
 
           Element(
             :"rdf:RDF",
@@ -48,6 +77,16 @@ module Sevgi
         end
 
         # rubocop:disable Metrics/MethodLength
+        # Builds a Creative Commons RDF Work element.
+        # @param kwargs [Hash] RDF work options
+        # @option kwargs [String] :title work title
+        # @option kwargs [String] :description work description
+        # @option kwargs [String] :creator creator
+        # @option kwargs [String] :publisher publisher
+        # @option kwargs [String] :date date
+        # @option kwargs [String] :language language
+        # @option kwargs [String] :license license URL
+        # @return [Sevgi::Graphics::Element] RDF element
         def RDFWork(**kwargs, &block)
           RDF do
             Element(:"cc:Work", "rdf:about": "") do

data/lib/sevgi/graphics/mixtures/render.rb

@@ -3,18 +3,36 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for rendering SVG documents and children.
       module Render
+        # SVG source renderer.
+        # @api private
         class Renderer
+          # Default renderer options.
           DEFAULTS = {indent: "  ", linelength: 140, style: :hybrid}.freeze
 
+          # Attribute rendering strategies.
+          # @api private
           module Attributes
+            # Block-style attribute renderer.
+            # @api private
             module Block
+              # Renders attributes in block form.
+              # @param element [Sevgi::Graphics::Element] rendered element
+              # @param depth [Integer] element depth
+              # @return [void]
               def attributes(element, depth)
                 attributes_block(element, depth, element.attributes.to_xml_lines)
               end
             end
 
+            # Hybrid attribute renderer.
+            # @api private
             module Hybrid
+              # Renders attributes inline or in block form according to line length.
+              # @param element [Sevgi::Graphics::Element] rendered element
+              # @param depth [Integer] element depth
+              # @return [void]
               def attributes(element, depth)
                 if attributes_as_block?(lines = element.attributes.to_xml_lines, depth)
                   attributes_block(element, depth, lines)
@@ -23,16 +41,30 @@ module Sevgi
                 end
               end
 
+              # Reports whether attributes should be rendered in block form.
+              # @param lines [Array<String>] rendered attribute lines
+              # @param depth [Integer] element depth
+              # @return [Boolean]
               def attributes_as_block?(lines, depth)
                 linelength(lines, depth) > options[:linelength]
               end
 
+              # Returns the effective inline line length.
+              # @param lines [Array<String>] rendered attribute lines
+              # @param depth [Integer] element depth
+              # @return [Integer]
               def linelength(lines, depth)
                 indent(depth).length + lines.sum(&:length)
               end
             end
 
+            # Inline attribute renderer.
+            # @api private
             module Inline
+              # Renders attributes inline.
+              # @param element [Sevgi::Graphics::Element] rendered element
+              # @param depth [Integer] element depth
+              # @return [void]
               def attributes(element, depth)
                 attributes_inline(element, depth, element.attributes.to_xml_lines)
               end
@@ -47,17 +79,41 @@ module Sevgi
 
           private_constant :ELEMENTS_WITH_INLINE_CONTENT, :ELEMENTS_WITH_BLOCK_CONTENT, :SEPARATOR
 
-          attr_reader :root, :options, :output
+          # @return [Sevgi::Graphics::Element] root element
+          attr_reader :root
 
+          # @return [Hash] renderer options
+          attr_reader :options
+
+          # @return [Array<Array<String>>] buffered output lines
+          attr_reader :output
+
+          # Inline-content output splice helper.
+          # @api private
           class Inlines
+            # Inline mark with start, stop, and depth.
             Mark = Struct.new(:start, :stop, :depth)
 
+            # Creates an inline splice tracker.
+            # @return [void]
             def initialize = @marks = []
 
+            # Starts an inline splice range.
+            # @param index [Integer] output index
+            # @param depth [Integer] element depth
+            # @return [Array<Sevgi::Graphics::Mixtures::Render::Renderer::Inlines::Mark>]
             def start(index, depth) = @marks << Mark.new(start: index, depth:)
 
+            # Ends the latest inline splice range.
+            # @param index [Integer] output index
+            # @return [Integer]
             def stop(index) = @marks.last.stop = index
 
+            # Joins marked output ranges into inline content.
+            # @param output [Array<Array<String>, nil>] renderer output buffer
+            # @param indent [String] indentation unit
+            # @param separator [String] line separator
+            # @return [Array<Array<String>, nil>, nil]
             def join(output, indent:, separator:)
               return if @marks.empty?
 
@@ -75,6 +131,15 @@ module Sevgi
             end
           end
 
+          # @overload initialize(root, **options)
+          #   Creates a renderer.
+          #   @param root [Sevgi::Graphics::Element] root element
+          #   @param options [Hash] renderer options
+          #   @option options [String] :indent indentation unit
+          #   @option options [Integer] :linelength hybrid attribute line length
+          #   @option options [Symbol] :style attribute style, one of :hybrid, :inline, or :block
+          #   @return [void]
+          #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
           def initialize(root, **)
             @root = root
             @options = DEFAULTS.merge(**)
@@ -84,14 +149,27 @@ module Sevgi
             build
           end
 
+          # @overload call(root, **options)
+          #   Renders a root element.
+          #   @param root [Sevgi::Graphics::Element] root element
+          #   @param options [Hash] renderer options
+          #   @return [String] SVG source
+          #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
           def self.call(root, **) = new(root, **).call(*root.class.preambles)
 
+          # Appends rendered lines to the output buffer.
+          # @param depth [Integer, nil] indentation depth
+          # @param lines [Array<String>] rendered lines
+          # @return [Array<Array<String>>, nil]
           def append(depth, *lines)
             return if lines.empty?
 
             output.append(lines.map { "#{indent(depth) if depth}#{it}" })
           end
 
+          # Renders the document.
+          # @param preambles [Array<String>] preamble lines
+          # @return [String] SVG source
           def call(*preambles)
             output.append(preambles) unless preambles.empty?
 
@@ -108,6 +186,8 @@ module Sevgi
           attr_reader :inlines
 
           def attributes_block(element, depth, lines)
+            return attributes_inline(element, depth, lines) if lines.empty?
+
             append(depth, "<#{element.name}")
             append(depth + 1, *lines)
             append(depth, ">") unless childless?(element)
@@ -202,9 +282,17 @@ module Sevgi
 
         private_constant :Renderer
 
+        # @overload Render(**options)
+        #   Renders this element as SVG source.
+        #   @param options [Hash] renderer options
+        #   @return [String] SVG source
+        #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
         def Render(**) = Renderer.(self, **)
 
-        def Render!(separator = SEPARATOR * 2) = children.map(&:Render!).join(separator)
+        # Renders only this element's children.
+        # @param separator [String] separator between child documents
+        # @return [String] rendered children
+        def RenderChildren(separator = "\n\n") = children.map(&:Render).join(separator)
       end
     end
   end

data/lib/sevgi/graphics/mixtures/save.rb

@@ -5,13 +5,23 @@ require "fileutils"
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for writing rendered SVG output.
       module Save
+        # Default SVG extension.
         EXT = ".svg"
 
-        def Out(*, **, &filter)
-          F.out(self.(**), *, &filter)
+        # Writes rendered SVG to standard output.
+        # @param kwargs [Hash] render options
+        # @return [Object] F.out return value
+        def Out(**kwargs, &filter)
+          F.out(self.(**kwargs), &filter)
         end
 
+        # Saves rendered SVG to a path derived from the caller by default.
+        # @param path [String, nil] output path or directory
+        # @param default [String, nil] default output path
+        # @param backup_suffix [String, nil] suffix used for an existing-file backup
+        # @return [Object] F.out return value
         def Save(path = nil, default: nil, backup_suffix: nil, &filter)
           default ||= F.subext(EXT, caller_locations(1..1).first.path)
 
@@ -26,7 +36,15 @@ module Sevgi
             ::FileUtils.cp(path, "#{path}#{backup_suffix}")
           end
 
-          Out(path, &filter)
+          Write(path, &filter)
+        end
+
+        # Writes rendered SVG to a path.
+        # @param path [String] output path
+        # @param kwargs [Hash] render options
+        # @return [Object] F.out return value
+        def Write(path, **kwargs, &filter)
+          F.out(self.(**kwargs), path, &filter)
         end
       end
     end

data/lib/sevgi/graphics/mixtures/symbols.rb

@@ -3,7 +3,14 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for expanding callable modules into SVG symbols.
       module Symbols
+        # Renders module callables as symbols under defs.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] defs attributes
+        # @return [Sevgi::Graphics::Element] defs element
+        # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Symbols(mod, *args, **kwargs, &block)
           CallWithin(mod, :defs, :symbol, *args, **kwargs) do |name, element|
             element[:id] = block ? block.call(name) : name.to_s.split("_").join("-")

data/lib/sevgi/graphics/mixtures/tile.rb

@@ -4,9 +4,22 @@ module Sevgi
   module Graphics
     module Mixtures
       # rubocop:disable Metrics/MethodLength
+      # DSL helpers for repeated SVG use elements.
       module Tile
+        # Prefix used for generated tile CSS classes.
         PREFIX = "tile"
 
+        # Builds a two-dimensional tile grid.
+        # @param id [String] referenced template id
+        # @param nx [Integer] number of columns
+        # @param dx [Numeric] horizontal spacing
+        # @param ox [Numeric] horizontal offset
+        # @param ny [Integer] number of rows
+        # @param dy [Numeric] vertical spacing
+        # @param oy [Numeric] vertical offset
+        # @param proc [Proc, nil] optional coordinate/customization proc
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def Tile(
           id = Undefined,
           nx: Undefined,
@@ -48,8 +61,14 @@ module Sevgi
           end
         end
 
-        def Tile!(id, klass = PREFIX, ...) = g(id:, class: klass) { Tile(id, ...) }
-
+        # Builds a one-dimensional horizontal tile row.
+        # @param id [String] referenced template id
+        # @param n [Integer] number of instances
+        # @param d [Numeric] horizontal spacing
+        # @param o [Numeric] horizontal offset
+        # @param proc [Proc, nil] optional coordinate/customization proc
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileX(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
           Helper.assert(id:, n:, d:, o:, proc:)
 
@@ -75,8 +94,14 @@ module Sevgi
           end
         end
 
-        def TileX!(id, klass = PREFIX, ...) = g(id:, class: klass) { TileX(id, ...) }
-
+        # Builds a one-dimensional vertical tile column.
+        # @param id [String] referenced template id
+        # @param n [Integer] number of instances
+        # @param d [Numeric] vertical spacing
+        # @param o [Numeric] vertical offset
+        # @param proc [Proc, nil] optional coordinate/customization proc
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when a required tile argument is missing or invalid
         def TileY(id = Undefined, n: Undefined, d: Undefined, o: 0, proc: nil, &block)
           Helper.assert(id:, n:, d:, o:, proc:)
 
@@ -102,11 +127,12 @@ module Sevgi
           end
         end
 
-        def TileY!(id, klass = PREFIX, ...) = g(id:, class: klass) { TileY(id, ...) }
-
+        # Tile argument validation and class helpers.
+        # @api private
         module Helper
           extend self
 
+          # Argument validators for tile helpers.
           ASSERTION = {
             id: proc { |name, value| "Argument '#{name}' must be a string" unless value.is_a?(::String) },
             n: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
@@ -121,6 +147,10 @@ module Sevgi
             proc: proc { |name, value| "Argument '#{name}' must be a proc" unless value.nil? || value.is_a?(::Proc) }
           }.freeze
 
+          # Validates tile arguments.
+          # @param kwargs [Hash] tile arguments
+          # @return [nil]
+          # @raise [Sevgi::ArgumentError] when an argument is missing or invalid
           def assert(**kwargs)
             kwargs.each do |name, value|
               issue = "Argument '#{name}' required" if value == Undefined
@@ -135,6 +165,11 @@ module Sevgi
             # rubocop:enable Metrics/MethodLength
           end
 
+          # Returns positional tile CSS classes.
+          # @param as [String] class axis label
+          # @param index [Integer] zero-based index
+          # @param upper [Integer] item count
+          # @return [Array<String>]
           def classify(as:, index:, upper:)
             [].tap do |classes|
               classes << "#{PREFIX}-#{as}-#{index + 1}"

data/lib/sevgi/graphics/mixtures/transform.rb

@@ -3,7 +3,14 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for SVG transform attributes.
       module Transform
+        # Aligns an inner box inside an outer box.
+        # @param position [Symbol, String, nil] alignment name
+        # @param inner [#width, #height, nil] inner box
+        # @param outer [#width, #height, nil] outer box
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when alignment is unsupported
         def Align(position, inner:, outer:)
           return self unless position && inner && outer
 
@@ -15,34 +22,47 @@ module Sevgi
           end
         end
 
+        # Appends a scale(-1, -1) transform.
+        # @return [Sevgi::Graphics::Element] self
         def Flip
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, 1) scale(1, 1)"
+            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, -1)"
           end
         end
 
+        # Appends a horizontal flip transform.
+        # @return [Sevgi::Graphics::Element] self
         def FlipX
           tap do
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(-1, 1)"
           end
         end
 
+        # Appends a vertical flip transform.
+        # @return [Sevgi::Graphics::Element] self
         def FlipY
           tap do
-            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(1, -11)"
+            attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(1, -1)"
           end
         end
 
+        # Appends a six-value SVG matrix transform.
+        # @param values [Array<Numeric>] matrix values
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when exactly six values are not supplied
         def Matrix(*values)
           tap do
             ArgumentError.("Incorrect transform matrix (six values required): #{values}") if values.size != 6
 
-            next if values.map(&:to_f).all? { it == 0.0 }
-
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "matrix(#{values.join(" ")})"
           end
         end
 
+        # Appends an SVG rotate transform.
+        # @param a [Numeric] angle in degrees
+        # @param origin [Array<Numeric>] optional x and y origin
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ArgumentError] when origin is not two coordinates
         def Rotate(a, *origin)
           tap do
             if !origin.empty? && origin.size != 2
@@ -55,28 +75,39 @@ module Sevgi
           end
         end
 
-        def Rotate90(...) = Rotate(90, ...)
-
-        def Rotate09(...) = Rotate(-90, ...)
-
+        # @overload RotateRight(*origin)
+        #   Appends a 90-degree SVG rotate transform.
+        #   @param origin [Array<Numeric>] optional x and y origin
+        #   @return [Sevgi::Graphics::Element] self
+        def RotateRight(...) = Rotate(90, ...)
+
+        # @overload RotateLeft(*origin)
+        #   Appends a -90-degree SVG rotate transform.
+        #   @param origin [Array<Numeric>] optional x and y origin
+        #   @return [Sevgi::Graphics::Element] self
+        def RotateLeft(...) = Rotate(-90, ...)
+
+        # Appends an SVG scale transform.
+        # @param x [Numeric] x scale, or uniform scale when y is nil
+        # @param y [Numeric, nil] y scale
+        # @return [Sevgi::Graphics::Element] self
         def Scale(x, y = nil)
           tap do
-            next if x.to_f == 0.0 && (y.nil? || y.to_f == 0.0)
-
             attributes[:"transform#{ATTRIBUTE_UPDATE_SUFFIX}"] = "scale(#{(y ? [x, y] : [x]).join(", ")})"
           end
         end
 
-        def Scale!(...)
-          Scale(...).tap do
-            attributes[:"vector-effect"] = "non-scaling-stroke" unless attributes[:"vector-effect"]
-          end
-        end
-
+        # Appends a skew transform through an SVG matrix.
+        # @param ax [Numeric] x skew angle in degrees
+        # @param ay [Numeric] y skew angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def Skew(ax, ay)
           Matrix(1.0, ::Math.tan(ay / 180.0 * ::Math::PI), ::Math.tan(ax / 180.0 * ::Math::PI), 1.0, 0.0, 0.0)
         end
 
+        # Appends an SVG skewX transform.
+        # @param a [Numeric] angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def SkewX(a)
           tap do
             next if a.to_f == 0.0
@@ -85,6 +116,9 @@ module Sevgi
           end
         end
 
+        # Appends an SVG skewY transform.
+        # @param a [Numeric] angle in degrees
+        # @return [Sevgi::Graphics::Element] self
         def SkewY(a)
           tap do
             next if a.to_f == 0.0
@@ -93,6 +127,10 @@ module Sevgi
           end
         end
 
+        # Appends an SVG translate transform.
+        # @param x [Numeric] x translation
+        # @param y [Numeric, nil] y translation
+        # @return [Sevgi::Graphics::Element] self
         def Translate(x, y = nil)
           tap do
             next if x.to_f == 0.0 && (y.nil? || y.to_f == 0.0)

data/lib/sevgi/graphics/mixtures/underscore.rb

@@ -3,18 +3,27 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for floating text, comments, and inherited internal attributes.
       module Underscore
+        # Creates a floating content element.
+        # @param contents [Array<Object>] text or content objects
+        # @return [Sevgi::Graphics::Element] floating element
         def _(*contents)
           Element(:_, *contents)
         end
 
+        # Adds an XML comment.
+        # @param comment [String] comment text
+        # @return [Sevgi::Graphics::Element] floating comment element
         def Comment(comment)
           _(Content.verbatim("<!-- #{comment} -->"))
         end
 
+        # Merges internal ancestral attributes from the document root to this element.
+        # @return [Hash] merged internal attributes
         def Ancestral
           {}.tap do |result|
-            Root.Traverse() { |element| result.merge!(element[:_]) if element.has?(:_) }
+            Root().Traverse() { |element| result.merge!(element[:_]) if element.has?(:_) }
           end
         end
       end

data/lib/sevgi/graphics/mixtures/validate.rb

@@ -3,19 +3,28 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # DSL helpers for SVG standard validation.
       module Validate
+        # Returns text content used as SVG character data.
+        # @return [String, nil] joined text content or nil
         def CData
           return if !contents || contents.empty?
 
           Content.text(contents)
         end
 
+        # Reports whether a namespace is available on this element or an ancestor.
+        # @param name [Symbol, String] namespace suffix without xmlns:
+        # @return [Boolean]
         def NS?(name)
           self.class.attributes.key?(key = :"xmlns:#{name}") || TraverseUp { Stay(true) if it.has?(key) } || false
         end
 
         require "sevgi/standard"
 
+        # Validates this subtree against the SVG standard metadata.
+        # @return [Sevgi::Graphics::Element] self
+        # @raise [Sevgi::ValidationError] when SVG validation fails
         def Validate
           Traverse do |element|
             Standard.conform(
@@ -27,7 +36,12 @@ module Sevgi
           end
         end
 
-      rescue ::LoadError
+      rescue ::LoadError => e
+        raise unless e.path == "sevgi/standard"
+
+        # @overload Validate
+        #   No-op validation fallback when sevgi/standard is unavailable.
+        #   @return [nil]
         def Validate(...)
         end
       end