sevgi-graphics 0.73.2 → 0.94.0

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

@@ -3,7 +3,15 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # Inkscape-specific SVG DSL helpers.
       module Inkscape
+        # Adds Inkscape template metadata.
+        # @param name [String] template name
+        # @param desc [String, nil] short description
+        # @param author [String, nil] author
+        # @param date [String, nil] date
+        # @param keywords [Array<String>, String, nil] keywords
+        # @return [Sevgi::Graphics::Element] template metadata element
         def InkscapeTemplateInfo(name:, desc: nil, author: nil, date: nil, keywords: nil)
           Element(:"inkscape:_templateinfo") do
             Element(:"inkscape:_name", name)
@@ -14,29 +22,59 @@ module Sevgi
           end
         end
 
+        # Renders a callable module inside a group.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] group attributes
+        # @return [Sevgi::Graphics::Element] group element
+        # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Group(mod, *args, **kwargs, &block)
           kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
           g(**kwargs) { Call(mod, *args, &block) }
         end
 
+        # Renders a callable module inside an Inkscape layer.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] layer attributes
+        # @return [Sevgi::Graphics::Element] layer element
+        # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer(mod, *args, **kwargs, &block)
           kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
           layer(**kwargs) { Call(mod, *args, &block) }
         end
 
+        # Renders a callable module inside an insensitive Inkscape layer.
+        # @param mod [Module] callable drawing module
+        # @param args [Array<Object>] callable arguments
+        # @param kwargs [Hash] layer attributes
+        # @return [Sevgi::Graphics::Element] layer element
+        # @raise [Sevgi::ArgumentError] when mod is not a plain module
         def Layer!(mod, *args, **kwargs, &block)
           kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
           layer!(**kwargs) { Call(mod, *args, &block) }
         end
 
+        # @overload layer(**attributes)
+        #   Builds an Inkscape layer group.
+        #   @param attributes [Hash] layer attributes
+        #   @return [Sevgi::Graphics::Element] layer group
         def layer(**, &block)
           g("inkscape:groupmode": "layer", **, &block)
         end
 
+        # @overload layer!(**attributes)
+        #   Builds an insensitive Inkscape layer group.
+        #   @param attributes [Hash] layer attributes
+        #   @return [Sevgi::Graphics::Element] layer group
         def layer!(**, &block)
           layer("sodipodi:insensitive": "true", **, &block)
         end
 
+        # Builds an Inkscape namedview containing page elements.
+        # @param pages [Array<Hash>] page attribute hashes
+        # @param id [String] namedview id
+        # @return [Sevgi::Graphics::Element] namedview element
         def Pages(*pages, id: "namedview", **, &block)
           Element(:"sodipodi:namedview", id:, **) do
             pages.each_with_index do |page, i|
@@ -48,12 +86,20 @@ module Sevgi
           end
         end
 
+        # Builds a tabular set of Inkscape pages.
+        # @param rows [Integer] number of rows
+        # @param cols [Integer] number of columns
+        # @param width [Numeric] page width
+        # @param height [Numeric] page height
+        # @param gap [Numeric] gap between pages
+        # @param id [String] namedview id
+        # @return [Array<Array>] matrix entries as x, y, and label tuples
         def PagesTabular(rows:, cols:, width:, height:, gap:, id: "namedview", **)
           [].tap do |matrix|
             Element(:"sodipodi:namedview", id:) do
               rows.times do |row|
                 cols.times do |col|
-                  matrix << (x, y, label = col * (height + gap), row * (width + gap), "#{row + 1}x#{col + 1}")
+                  matrix << (x, y, label = col * (width + gap), row * (height + gap), "#{row + 1}x#{col + 1}")
                   Element(:"inkscape:page", id: "pageview-#{label}", x:, y:, width:, height:, **)
                 end
               end
@@ -62,6 +108,10 @@ module Sevgi
         end
 
         # Internal symbol which does not show up Symbols Menu
+        # @overload symbol!(**attributes)
+        #   Builds an Inkscape symbol group hidden from the symbols menu.
+        #   @param attributes [Hash] symbol attributes
+        #   @return [Sevgi::Graphics::Element] symbol group
         def symbol!(**, &block)
           if Is?(:defs)
             g(role: "inkscape:symbol", **, &block)
@@ -70,10 +120,6 @@ module Sevgi
           end
         end
 
-        def Symbol!(mod, *args, **kwargs, &block)
-          kwargs = kwargs.merge(id: F.demodulize(mod).to_sym) unless kwargs.key?(:id)
-          symbol!(**kwargs) { Call(mod, *args, &block) }
-        end
       end
     end
   end

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

@@ -2,17 +2,29 @@
 
 module Sevgi
   module Graphics
+    # Raised when graphics lint checks fail.
     LintError = Class.new(Error)
 
     module Mixtures
+      # DSL helpers for pre-render structural linting.
       module Lint
+        # @overload Lint
+        #   Runs graphics lint checks.
+        #   @return [true]
+        #   @raise [Sevgi::Graphics::LintError] when a lint check fails
         def Lint(...)
           IdentitiesAreUniq.(self, ...)
         end
 
+        # Lint check that rejects duplicate visible ids.
+        # @api private
         module IdentitiesAreUniq
           extend self
 
+          # Checks an element subtree for duplicate ids.
+          # @param element [Sevgi::Graphics::Element] root element
+          # @return [true]
+          # @raise [Sevgi::Graphics::LintError] when duplicate ids exist
           def call(element)
             return true unless (identifiers = element.Identifiers()).conflict?
 

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

@@ -3,9 +3,20 @@
 module Sevgi
   module Graphics
     module Mixtures
+      # Compatibility helpers for profiles that do not load richer mixtures.
       module Polyfills
+        # @overload layer(*args, **attributes)
+        #   Builds a generic group as a layer fallback.
+        #   @param args [Array<Object>] group content arguments
+        #   @param attributes [Hash] group attributes
+        #   @return [Sevgi::Graphics::Element] group element
         def layer(...) = g(...)
 
+        # @overload symbol!(*args, **attributes)
+        #   Builds a regular symbol as a fallback for hidden symbols.
+        #   @param args [Array<Object>] symbol content arguments
+        #   @param attributes [Hash] symbol attributes
+        #   @return [Sevgi::Graphics::Element] symbol element
         def symbol!(...) = symbol(...)
       end
     end

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,34 +79,89 @@ 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)
 
-            def initialize = @marks = []
+            # Creates an inline splice tracker.
+            # @return [void]
+            def initialize
+              @marks = []
+              @stack = []
+            end
 
-            def start(index, depth) = @marks << Mark.new(start: index, depth:)
+            # 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
+                @stack << mark
+              end
+            end
 
-            def stop(index) = @marks.last.stop = index
+            # 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
 
+              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?
 
-              @marks.each do |mark|
-                depth = mark.depth
-
-                ((mark.start + 1)..mark.stop).each do |i|
-                  output[i].map! { |line| line.delete_prefix(indent * (depth + 1)) }
-                  output[mark.start][-1] += output[i].join(separator)
-                  output[i] = nil
-                end
-              end
+              @marks.reverse_each { |mark| join_mark(output, mark, indent:, separator:) }
 
               output.compact!
             end
+
+            private
+
+            def join_mark(output, mark, indent:, separator:)
+              PanicError.("Inline content range was not closed") unless mark.stop
+
+              ((mark.start + 1)..mark.stop).each do |index|
+                lines = output[index]
+                next unless lines
+
+                lines.map! { |line| line.delete_prefix(indent * (mark.depth + 1)) }
+                output[mark.start][-1] += lines.join(separator)
+                output[index] = nil
+              end
+            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 +171,34 @@ 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)
 
+          # Renders a root element without document preambles.
+          # @param root [Sevgi::Graphics::Element] root element
+          # @param options [Hash] renderer options
+          # @return [String] SVG fragment source
+          # @raise [Sevgi::ArgumentError] when style is missing or unsupported
+          def self.fragment(root, **options) = new(root, **options).call
+
+          # 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 +215,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 +311,22 @@ module Sevgi
 
         private_constant :Renderer
 
+        # @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
+        #   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.
+        #   @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.
+        # Child render output omits document preambles and preserves each child's text whitespace and inline
+        # mixed-content formatting.
+        # @param separator [String] separator between child documents
+        # @return [String] rendered child fragments
+        def RenderChildren(separator = "\n\n") = children.map { Renderer.fragment(it) }.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,16 +127,17 @@ 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? },
-            nx: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
-            ny: proc { |name, value| "Argument '#{name}' must be a positive integer" unless value.positive? },
+            n: proc { |name, value| positive_integer_issue(name, value) },
+            nx: proc { |name, value| positive_integer_issue(name, value) },
+            ny: proc { |name, value| positive_integer_issue(name, value) },
             d: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
             dx: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
             dy: proc { |name, value| "Argument '#{name}' must be a number" unless value.is_a?(::Numeric) },
@@ -121,6 +147,18 @@ module Sevgi
             proc: proc { |name, value| "Argument '#{name}' must be a proc" unless value.nil? || value.is_a?(::Proc) }
           }.freeze
 
+          # Returns a validation issue unless value is a positive integer.
+          # @param name [Symbol] argument name
+          # @param value [Object] argument value
+          # @return [String, nil] validation issue
+          def positive_integer_issue(name, value)
+            "Argument '#{name}' must be a positive integer" unless value.is_a?(::Integer) && value.positive?
+          end
+
+          # 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 +173,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}"