sevgi-graphics 0.98.2 → 1.0.0

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

@@ -10,8 +10,9 @@ module Sevgi
         # moved to non-rendering `-id` metadata before the optional block runs, allowing the block to derive replacement
         # ids without rendering duplicates. A pre-existing `-id` takes precedence over the visible id.
         # Translation and parent channels are validated before the subtree is copied or the customization block runs.
-        # @param dx [Numeric, nil] finite x translation; nil omits the axis
-        # @param dy [Numeric, nil] finite y translation; nil omits the axis
+        # The copied subtree has no parent during customization and is attached to the target parent afterward.
+        # @param dx [Numeric, nil] finite x translation. Nil omits the axis
+        # @param dy [Numeric, nil] finite y translation. Nil omits the axis
         # @param parent [Sevgi::Graphics::Element, nil] explicit parent, or the source parent when nil
         # @yield [element] optional customization hook for each copied element
         # @yieldparam element [Sevgi::Graphics::Element] copied element
@@ -27,7 +28,7 @@ module Sevgi
         #   end
         def Duplicate(dx: nil, dy: nil, parent: nil, &block)
           dx, dy, target = Subtree.channels(self, dx, dy, parent)
-          duplicated = Subtree.copy(self)
+          duplicated = dup
           Subtree.prepare(duplicated, &block)
           Subtree.translate(duplicated, dx, dy)
           Subtree.attach(duplicated, target)
@@ -80,19 +81,6 @@ module Sevgi
             [dx, dy, target]
           end
 
-          # Builds an independent copy of an element subtree.
-          # @param element [Sevgi::Graphics::Element] source subtree root
-          # @param parent [Sevgi::Graphics::Element, Object] parent for the copied root
-          # @return [Sevgi::Graphics::Element] copied subtree root
-          def self.copy(element, parent = Element.send(:tree_parent, element))
-            element.dup.tap do |duplicated|
-              duplicated.send(:parent=, parent)
-              duplicated.send(:attributes=, element.attributes.dup)
-              duplicated.send(:contents=, element.contents.map(&:dup))
-              duplicated.send(:children=, element.children.map { |child| copy(child, duplicated) })
-            end
-          end
-
           # Removes copied public ids and applies an optional customization hook.
           # @api private
           def self.prepare(element, &block)

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

@@ -4,6 +4,8 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for native SVG export formats.
+      # Export CSS is a late adjustment after document checks. Its supported XML endings and cascade limitations are
+      # documented in {Sevgi::Sundries::Export}. The source callback receives SVG after CSS insertion.
       module Export
         # Validates the closed export option channel before optional components load or rendering starts.
         # @api private

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

@@ -6,10 +6,10 @@ module Sevgi
       # DSL helpers for drawing geometry values and geometry-derived hatch lines.
       #
       # `Draw` delegates to each geometry object's drawing protocol. `Hatch`
-      # first sweeps interior spans through a closed lined element, then draws
-      # them. Its `angle` describes line direction; `step` is perpendicular
+      # first sweeps interior spans through a closed geometry element, then draws
+      # them. Its `angle` describes line direction. `step` is perpendicular
       # spacing. The default initial line passes through `element.position`.
-      # The built-in `:inkscape` document profile includes this mixture;
+      # The built-in `:inkscape` document profile includes this mixture.
       # `:minimal`, `:default`, and `:html` do not.
       #
       # Hatch materializes separate finite SVG path elements. When only a repeated visual fill matters, use an SVG
@@ -52,7 +52,7 @@ module Sevgi
         #   Sevgi::Graphics.SVG(:inkscape) do
         #     Hatch region, initial: [2, 8], angle: 0, step: 3
         #   end
-        # @param element [Sevgi::Geometry::Element::Lined] lined geometry element to sweep
+        # @param element [Sevgi::Geometry::Element] geometry element to sweep
         # @param angle [Numeric] hatch angle in degrees
         # @param step [Numeric] distance between hatch lines
         # @param initial [Sevgi::Geometry::Point, Array<Numeric>, nil] initial sweep point, or nil for element.position
@@ -72,7 +72,7 @@ module Sevgi
             MissingComponentError.("sevgi/geometry")
           end
 
-          initial = element.position if initial.nil? && element.is_a?(Geometry::Element::Lined)
+          initial = element.position if initial.nil? && element.is_a?(Geometry::Element)
           Draw(Geometry::Operation.sweep!(element, initial:, angle:, step:), **kwargs)
         end
       end

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

@@ -6,7 +6,7 @@ module Sevgi
       # DSL helpers for collecting and hiding SVG ids.
       module Identify
         # Immutable snapshot of every rendered element id under a subtree. Keys are the serialized id values, including
-        # `"false"` and the empty String. Keys and containers are owned by the index; values retain references to the
+        # `"false"` and the empty String. Keys and containers are owned by the index. Values retain references to the
         # elements present when the snapshot is built. Later tree changes require a new index.
         class Identifiers
           # @return [Sevgi::Graphics::Element] indexed root element

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

@@ -48,7 +48,7 @@ module Sevgi
         #   Sevgi::Graphics.SVG(:inkscape) { Group drawing, attributes: {id: "drawing"} }
         # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param attributes [Hash] group attributes; String and Symbol names are normalized and must not collide
+        # @param attributes [Hash] group attributes. String and Symbol names are normalized and must not collide
         # @param kwargs [Hash] callable keyword arguments
         # @yield forwards customization to the callable module
         # @yieldreturn [Object] callable customization result
@@ -65,7 +65,7 @@ module Sevgi
         # Named modules default the layer id to their final constant name. Anonymous modules omit the id unless supplied.
         # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param attributes [Hash] layer attributes; String and Symbol names are normalized and must not collide
+        # @param attributes [Hash] layer attributes. String and Symbol names are normalized and must not collide
         # @param kwargs [Hash] callable keyword arguments
         # @yield forwards customization to the callable module
         # @yieldreturn [Object] callable customization result
@@ -82,7 +82,7 @@ module Sevgi
         # Named modules default the layer id to their final constant name. Anonymous modules omit the id unless supplied.
         # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
-        # @param attributes [Hash] layer attributes; String and Symbol names are normalized and must not collide
+        # @param attributes [Hash] layer attributes. String and Symbol names are normalized and must not collide
         # @param kwargs [Hash] callable keyword arguments
         # @yield forwards customization to the callable module
         # @yieldreturn [Object] callable customization result
@@ -163,7 +163,7 @@ module Sevgi
             def channels(namedview, page)
               ArgumentError.("Namedview attributes must be a Hash") unless namedview.is_a?(::Hash)
               ArgumentError.("Page attributes must be a Hash") unless page.is_a?(::Hash)
-              [Attribute.defaults(namedview, id: "namedview"), Attribute.normalize(page)]
+              [Attribute.defaults(namedview, id: "namedview"), page_attributes(page)]
             end
 
             # Normalizes one explicit or generated page id.
@@ -181,7 +181,7 @@ module Sevgi
             # @api private
             def normalize(attributes, defaults, index)
               ArgumentError.("Page #{index + 1} must be a Hash") unless attributes.is_a?(::Hash)
-              attributes = defaults.merge(Attribute.normalize(attributes))
+              attributes = defaults.merge(page_attributes(attributes))
               %i[x y].each { number(attributes, it, index) }
               %i[width height].each do |field|
                 number(attributes, field, index, positive: true)
@@ -190,6 +190,19 @@ module Sevgi
               identify(attributes, index)
             end
 
+            # Coerces numeric page fields before attribute snapshots stringify mutable numeric subclasses.
+            def page_attributes(attributes)
+              Attribute.normalize(
+                attributes.to_h do |key, value|
+                  if %w[x y width height].include?(key.to_s) && value.is_a?(::Numeric)
+                    value = Scalar.number(value, context: "page", field: key)
+                  end
+
+                  [key, value]
+                end
+              )
+            end
+
             # Validates and normalizes page-grid arguments.
             # @return [Array<(Integer, Float)>] normalized width, height, and gap
             # @raise [Sevgi::ArgumentError] when a count, dimension, or gap is invalid
@@ -239,9 +252,9 @@ module Sevgi
         #       page: {class: "print"}
         #     )
         #   end
-        # @param pages [Array<Hash>] page attribute hashes; numeric page fields are normalized to SVG numbers
-        # @param namedview [Hash] namedview attributes; String and Symbol names are normalized and must not collide
-        # @param page [Hash] page defaults; normalized page attributes override these defaults by name
+        # @param pages [Array<Hash>] page attribute hashes. Numeric page fields are normalized to SVG numbers
+        # @param namedview [Hash] namedview attributes. String and Symbol names are normalized and must not collide
+        # @param page [Hash] page defaults. Normalized page attributes override these defaults by name
         # @yield [page] customizes each generated page element
         # @yieldparam page [Sevgi::Graphics::Element] generated page element
         # @yieldreturn [Object] ignored customization result
@@ -262,8 +275,8 @@ module Sevgi
         # @param width [Numeric] finite positive page width, normalized to an SVG number
         # @param height [Numeric] finite positive page height, normalized to an SVG number
         # @param gap [Numeric] finite non-negative gap, normalized to an SVG number
-        # @param namedview [Hash] namedview attributes; String and Symbol names are normalized and must not collide
-        # @param page [Hash] page defaults; normalized page attributes override these defaults by name
+        # @param namedview [Hash] namedview attributes. String and Symbol names are normalized and must not collide
+        # @param page [Hash] page defaults. Normalized page attributes override these defaults by name
         # @yield [page] customizes each generated page element
         # @yieldparam page [Sevgi::Graphics::Element] generated page element
         # @yieldreturn [Object] ignored customization result

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

@@ -114,7 +114,7 @@ module Sevgi
         def License_LAL(**kwargs, &block) = License(**kwargs, license: "https://artlibre.org/licence/lal/en/", &block)
 
         # Builds an RDF root element.
-        # @param kwargs [Hash] options; RDF currently accepts none
+        # @param kwargs [Hash] options. RDF currently accepts none
         # @yield evaluates the RDF drawing DSL
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element

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

@@ -13,68 +13,6 @@ module Sevgi
           STYLES = %i[hybrid inline block].freeze
           SVG_NAMESPACE = "http://www.w3.org/2000/svg"
 
-          # 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.send(: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.send(:xml_lines), depth)
-                  attributes_block(element, depth, lines)
-                else
-                  attributes_inline(element, depth, lines)
-                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.send(:xml_lines))
-              end
-            end
-          end
-
-          private_constant :Attributes
-
           ELEMENTS_WITH_INLINE_CONTENT = %i[title].freeze
           ELEMENTS_WITH_BLOCK_CONTENT = %i[style].freeze
           SEPARATOR = "\n"
@@ -102,17 +40,11 @@ module Sevgi
             # Inline mark with start, stop, and depth.
             Mark = Struct.new(:start, :stop, :depth)
 
-            # Creates an inline splice tracker.
-            # @return [void]
             def initialize
               @marks = []
               @stack = []
             end
 
-            # Starts an inline splice range.
-            # @param index [Integer] output index
-            # @param depth [Integer] element depth
-            # @return [Sevgi::Graphics::Mixtures::Render::Renderer::Inlines::Mark] opened mark
             def start(index, depth)
               Mark.new(start: index, depth:).tap do |mark|
                 @marks << mark
@@ -120,10 +52,6 @@ module Sevgi
               end
             end
 
-            # Ends the innermost inline splice range.
-            # @param index [Integer] output index
-            # @return [Integer]
-            # @raise [Sevgi::PanicError] when no inline range is open
             def stop(index)
               mark = @stack.pop
               PanicError.("Inline content range was not opened") unless mark
@@ -131,12 +59,6 @@ module Sevgi
               mark.stop = index
             end
 
-            # 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]
-            # @raise [Sevgi::PanicError] when an inline range was not closed
             def join(output, indent:, separator:)
               return if @marks.empty?
 
@@ -175,8 +97,7 @@ module Sevgi
             @options = self.class.send(:validate, **)
             @output = []
             @inlines = Inlines.new
-
-            build
+            unclosed
           end
 
           # @overload call(root, **options)
@@ -246,6 +167,14 @@ module Sevgi
 
           attr_reader :inlines
 
+          def attributes(element, depth)
+            lines = element.attributes.send(:xml_lines)
+            block = options[:style] == :block ||
+              (options[:style] == :hybrid && indent(depth).length + lines.sum(&:length) > options[:linelength])
+
+            block ? attributes_block(element, depth, lines) : attributes_inline(element, depth, lines)
+          end
+
           def attributes_block(element, depth, lines)
             return attributes_inline(element, depth, lines) if lines.empty?
 
@@ -265,19 +194,6 @@ module Sevgi
             end
           end
 
-          def build
-            case options[:style]
-            when :hybrid
-              extend(Attributes::Hybrid)
-            when :inline
-              extend(Attributes::Inline)
-            when :block
-              extend(Attributes::Block)
-            end
-
-            unclosed
-          end
-
           def childless?(element)
             element.children.empty? && element.contents.empty?
           end
@@ -361,9 +277,9 @@ module Sevgi
 
         # @overload Render(**options)
         #   Renders this element as SVG source.
-        #   Elements with inline text content may also contain inline children such as `tspan`; the renderer keeps those
+        #   Elements with inline text content can also contain inline children such as `tspan`. The renderer keeps those
         #   descendants in the same text line. Whitespace inside content objects is preserved as given, and encoded
-        #   content is XML-escaped unless a verbatim content object is used. SVG `style` elements use block content;
+        #   content is XML-escaped unless a verbatim content object is used. SVG `style` elements use block content.
         #   same-named elements under a foreign default namespace retain ordinary inline text formatting.
         #   @example Keep every attribute on the element's opening line
         #     SVG(:minimal) { rect id: "card", width: 80, height: 40 }.Render(style: :inline)

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

@@ -54,10 +54,10 @@ module Sevgi
 
         # Saves rendered SVG when its content differs from the destination.
         # Relative destinations are expanded before being returned. When a non-empty backup suffix is given, an
-        # existing destination is copied immediately before replacement; unchanged saves leave both files untouched.
+        # existing destination is copied immediately before replacement. Unchanged saves leave both files untouched.
         # Missing parent directories are created. An existing directory target uses the default file name.
         # @example Save to a relative destination
-        #   path = Sevgi::Graphics.SVG(:minimal).Save("build/drawing.svg")
+        #   path = Sevgi::Graphics.SVG.Save("build/drawing.svg")
         #   path == File.expand_path("build/drawing.svg") # => true
         # @param path [String, #to_path, nil] output path or existing directory
         # @param default [String, #to_path, nil] default output path

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

@@ -65,7 +65,7 @@ module Sevgi
 
         private_constant :Expansion
 
-        # Renders module callables as symbols under defs. Named modules default the defs id to their final constant name;
+        # Renders module callables as symbols under defs. Named modules default the defs id to their final constant name.
         # anonymous modules omit the id unless supplied.
         # @param mod [Module] module extended with {Sevgi::Graphics::Module}
         # @param args [Array<Object>] callable arguments
@@ -78,7 +78,7 @@ module Sevgi
         #     def tick = path d: "M 0 2 L 2 4 L 6 0"
         #   end
         #   Sevgi::Graphics.SVG(:minimal) { Symbols icons }
-        # @param attributes [Hash] defs attributes; String and Symbol names are normalized and must not collide
+        # @param attributes [Hash] defs attributes. String and Symbol names are normalized and must not collide
         # @param ids [#call, nil] optional callable mapping each method name to a symbol id
         # @param kwargs [Hash] callable keyword arguments
         # @yield forwarded to each callable

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

@@ -8,7 +8,7 @@ module Sevgi
       # Use {Sevgi::Sundries::Tile} instead when Ruby code needs inspectable repeated geometry or row/column bounds
       # rather than SVG references.
       # @see Sevgi::Sundries::Tile
-      # @see https://sevgi.roktas.dev/sundries/#choose-a-layout-model Choosing a layout model
+      # @see https://sevgi.roktas.dev/layout/#choose-a-layout-model Choosing a layout model
       module Tile
         # Stable prefix used for generated tile CSS classes.
         PREFIX = "tile"
@@ -30,7 +30,7 @@ module Sevgi
         # @param dy [Numeric] finite vertical spacing, normalized before coordinates are rendered
         # @param oy [Numeric] finite vertical offset, normalized before coordinates are rendered
         # @param proc [Proc, nil] optional callback invoked for each use as `(element, x:, y:, nx:, ny:)`, with
-        #   zero-based coordinates and total counts; the callback may mutate the element and its return value is ignored
+        #   zero-based coordinates and total counts. The callback can mutate the element. Its return value is ignored
         # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
@@ -83,7 +83,7 @@ module Sevgi
         # @param d [Numeric] finite horizontal spacing, normalized before coordinates are rendered
         # @param o [Numeric] finite horizontal offset, normalized before coordinates are rendered
         # @param proc [Proc, nil] optional callback invoked for each use as `(element, x:, n:)`, with a zero-based column
-        #   and total count; the callback may mutate the element and its return value is ignored
+        #   and total count. The callback can mutate the element. Its return value is ignored
         # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self
@@ -117,7 +117,7 @@ module Sevgi
         # @param d [Numeric] finite vertical spacing, normalized before coordinates are rendered
         # @param o [Numeric] finite vertical offset, normalized before coordinates are rendered
         # @param proc [Proc, nil] optional callback invoked for each use as `(element, y:, n:)`, with a zero-based row and
-        #   total count; the callback may mutate the element and its return value is ignored
+        #   total count. The callback can mutate the element. Its return value is ignored
         # @yield evaluates the template drawing DSL in a generated `defs` group named by id
         # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] self

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

@@ -11,13 +11,18 @@ module Sevgi
       #     rect(width: 8, height: 4).Translate(12, 6).Rotate(15, 4, 2)
       #   end
       module Transform
+        # Keep box validation here: mixture helper methods would also enter the SVG DSL namespace.
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
         # 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
+        # @param inner [#width, #height, nil] inner box, with optional position exposing x and y
+        # @param outer [#width, #height, nil] outer box, with optional position exposing x and y
         # @return [Sevgi::Graphics::Element] self
         # @raise [Sevgi::ArgumentError] when alignment is unsupported
         # @raise [Sevgi::ArgumentError] when a box dimension is not a finite real number
+        # @raise [Sevgi::ArgumentError] when a supplied box position does not expose finite real x and y coordinates
+        # @note Size-only boxes have origin (0, 0). Positions describe known box geometry, not renderer-computed bounds.
         def Align(position, inner:, outer:)
           return self unless position && inner && outer
 
@@ -25,12 +30,26 @@ module Sevgi
           when :center
             dimensions = [inner.width, inner.height, outer.width, outer.height]
             iw, ih, ow, oh = dimensions.map { Scalar.number(it, context: "alignment", field: :dimension) }
-            Translate((ow - iw) / 2.0, (oh - ih) / 2.0)
+            origins = [inner, outer].map do |box|
+              next [0, 0] unless box.respond_to?(:position)
+
+              origin = box.position
+              unless origin.respond_to?(:x) && origin.respond_to?(:y)
+                ArgumentError.("Alignment box position must expose x and y")
+              end
+
+              [origin.x, origin.y].map { Scalar.number(it, context: "alignment", field: :position) }
+            end
+
+            (ix, iy), (ox, oy) = origins
+            Translate(ox - ix + ((ow - iw) / 2.0), oy - iy + ((oh - ih) / 2.0))
           else
             ArgumentError.("Unsupported alignment: #{position}")
           end
         end
 
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
         # Appends a scale(-1, -1) transform.
         # @return [Sevgi::Graphics::Element] self
         def Flip

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

@@ -18,7 +18,7 @@ module Sevgi
         # Adds an XML comment.
         # @param comment [Object] comment text
         # @return [Sevgi::Graphics::Element] floating comment element
-        # @raise [Sevgi::ArgumentError] when comment cannot be stringified as valid XML or would form malformed markup
+        # @raise [Sevgi::ArgumentError] when comment cannot be stringified as valid XML or forms malformed markup
         def Comment(comment)
           comment = XML.text(comment, context: "XML comment")
 
@@ -29,7 +29,7 @@ module Sevgi
         end
 
         # Merges `-context` metadata from the document root, ancestors, and this element.
-        # Only the direct root-to-self ancestor chain participates; sibling subtrees are ignored. When the same key is
+        # Only the direct root-to-self ancestor chain participates. Sibling subtrees are ignored. When the same key is
         # present on multiple chain elements, the nearest element to the receiver wins. Context remains available in
         # memory but is omitted from rendered SVG. It is unrelated to the `_:` XML namespace syntax preserved by
         # Derender.

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

@@ -5,6 +5,55 @@ module Sevgi
     module Mixtures
       # DSL wrappers for common SVG shapes and content patterns.
       module Wrappers
+        # rubocop:disable Metrics/ParameterLists
+
+        # Builds an elliptical arc path ending at an absolute point.
+        # SVG resolves the ellipse from its endpoints, radii, and flags, including radius correction and zero radii.
+        # @example Draw an upper semicircle in screen coordinates
+        #   Sevgi::Graphics.SVG { ArcTo x1: 0, y1: 10, x2: 20, y2: 10, rx: 10, ry: 10, sweep: true }
+        # @param x2 [Numeric] finite ending x coordinate
+        # @param y2 [Numeric] finite ending y coordinate
+        # @param rx [Numeric] finite local x radius
+        # @param ry [Numeric] finite local y radius
+        # @param x1 [Numeric] finite starting x coordinate
+        # @param y1 [Numeric] finite starting y coordinate
+        # @param rotation [Numeric] clockwise ellipse rotation in degrees
+        # @param large [Boolean] select the arc exceeding a half turn
+        # @param sweep [Boolean] select increasing parameter angles
+        # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not finite real or a flag is not Boolean
+        def ArcTo(x2:, y2:, rx:, ry:, x1: 0, y1: 0, rotation: 0, large: false, sweep: false, **)
+          x1, y1, x2, y2, rx, ry, rotation = Scalar.numbers([x1, y1, x2, y2, rx, ry, rotation], context: "absolute arc")
+          unless [large, sweep].all? { it.equal?(true) || it.equal?(false) }
+            ArgumentError.("Arc flags must be Boolean")
+          end
+
+          path(d: "M #{x1} #{y1} A #{rx} #{ry} #{rotation} #{large ? 1 : 0} #{sweep ? 1 : 0} #{x2} #{y2}", **)
+        end
+
+        # Builds an elliptical arc path ending at a relative offset.
+        # @param dx [Numeric] finite x displacement from the starting point
+        # @param dy [Numeric] finite y displacement from the starting point
+        # @param rx [Numeric] finite local x radius
+        # @param ry [Numeric] finite local y radius
+        # @param x [Numeric] finite starting x coordinate
+        # @param y [Numeric] finite starting y coordinate
+        # @param rotation [Numeric] clockwise ellipse rotation in degrees
+        # @param large [Boolean] select the arc exceeding a half turn
+        # @param sweep [Boolean] select increasing parameter angles
+        # @return [Sevgi::Graphics::Element] path element
+        # @raise [Sevgi::ArgumentError] when an operand is not finite real or a flag is not Boolean
+        # @see #ArcTo
+        def ArcBy(dx:, dy:, rx:, ry:, x: 0, y: 0, rotation: 0, large: false, sweep: false, **)
+          x, y, dx, dy, rx, ry, rotation = Scalar.numbers([x, y, dx, dy, rx, ry, rotation], context: "relative arc")
+          unless [large, sweep].all? { it.equal?(true) || it.equal?(false) }
+            ArgumentError.("Arc flags must be Boolean")
+          end
+
+          path(d: "M #{x} #{y} a #{rx} #{ry} #{rotation} #{large ? 1 : 0} #{sweep ? 1 : 0} #{dx} #{dy}", **)
+        end
+        # rubocop:enable Metrics/ParameterLists
+
         # Builds a line path ending at an absolute point.
         # @example Render a rational coordinate as an SVG number
         #   Sevgi::Graphics.SVG { LineTo(x2: Rational(1, 2), y2: 1) }

data/lib/sevgi/graphics/version.rb

@@ -3,6 +3,6 @@
 module Sevgi
   module Graphics
     # Current graphics component version.
-    VERSION = "0.98.2"
+    VERSION = "1.0.0"
   end
 end

data/lib/sevgi/graphics/xml.rb

@@ -11,8 +11,9 @@ module Sevgi
       NCNAME_CHAR = "#{NCNAME_START}\\-.0-9\u{B7}\u{300}-\u{36F}\u{203F}-\u{2040}".freeze
       NCNAME = "[#{NCNAME_START}][#{NCNAME_CHAR}]*".freeze
       QNAME = /\A#{NCNAME}(?::#{NCNAME})?\z/u
+      ILLEGAL_CHARACTER = /[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/u
 
-      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME
+      private_constant :NCNAME, :NCNAME_CHAR, :NCNAME_START, :QNAME, :ILLEGAL_CHARACTER
 
       class << self
         # Validates an XML 1.0 string representation.
@@ -104,8 +105,8 @@ module Sevgi
           ArgumentError.("#{context} must be valid UTF-8") unless value.valid_encoding?
 
           text = value.encode("UTF-8")
-          if (codepoint = text.each_codepoint.find { !legal_codepoint?(it) })
-            ArgumentError.("#{context} contains illegal character U+#{format("%04X", codepoint)}")
+          if (match = ILLEGAL_CHARACTER.match(text))
+            ArgumentError.("#{context} contains illegal character U+#{format("%04X", match[0].ord)}")
           end
 
           text
@@ -113,12 +114,6 @@ module Sevgi
           ArgumentError.("#{context} must be valid UTF-8: #{e.message}")
         end
 
-        def legal_codepoint?(codepoint)
-          [0x9, 0xA, 0xD].include?(codepoint) ||
-            (0x20..0xD7FF).cover?(codepoint) ||
-            (0xE000..0xFFFD).cover?(codepoint) ||
-            (0x10000..0x10FFFF).cover?(codepoint)
-        end
       end
     end