sevgi-graphics 0.94.0 → 0.98.2

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

@@ -4,66 +4,124 @@ module Sevgi
   module Graphics
     module Mixtures
       # DSL helpers for RDF and license metadata.
+      #
+      # @example Add Creative Commons metadata
+      #   Sevgi::Graphics.SVG :inkscape do
+      #     License_CC0 title: "Example", creator: "A. Creator"
+      #   end
       module RDF
+        WORK_OPTIONS = %i[title description creator publisher date language license].freeze
+        private_constant :WORK_OPTIONS
+
         # Adds RDF license metadata inside a metadata element.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
-        def License(**kwargs, &block) = metadata { RDFWork(**kwargs, &block) }
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
+        def License(**kwargs, &block)
+          unknown = kwargs.keys - WORK_OPTIONS
+          ArgumentError.("Unknown license options: #{unknown.join(", ")}") unless unknown.empty?
+
+          metadata { RDFWork(**kwargs, &block) }
+        end
+
+        # Adds Creative Commons BY license metadata.
+        # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
+        # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
+        def License_CC_BY(**kwargs, &block)
+          License(**kwargs, license: "https://creativecommons.org/licenses/by/4.0/", &block)
+        end
 
-        # Use SPDX license codes in underscored form: https://spdx.org/licenses/
-        #
         # Adds Creative Commons BY-SA license metadata.
         # @param kwargs [Hash] RDF work options
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] metadata element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
+        # @see #RDFWork
         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
+        # @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
         # @raise [Sevgi::ArgumentError] when no block is given
-        def RDF(**_kwargs, &block)
+        # @raise [Sevgi::ArgumentError] when an option is given
+        def RDF(**kwargs, &block)
+          ArgumentError.("Unknown RDF options: #{kwargs.keys.join(", ")}") unless kwargs.empty?
           ArgumentError.("Block required") unless block
 
           Element(
@@ -76,7 +134,6 @@ module Sevgi
           end
         end
 
-        # rubocop:disable Metrics/MethodLength
         # Builds a Creative Commons RDF Work element.
         # @param kwargs [Hash] RDF work options
         # @option kwargs [String] :title work title
@@ -86,8 +143,24 @@ module Sevgi
         # @option kwargs [String] :date date
         # @option kwargs [String] :language language
         # @option kwargs [String] :license license URL
+        #
+        # | Option | RDF element |
+        # | --- | --- |
+        # | `title` | `dc:title` |
+        # | `description` | `dc:description` |
+        # | `creator` | `dc:creator` |
+        # | `publisher` | `dc:publisher` |
+        # | `date` | `dc:date` |
+        # | `language` | `dc:language` |
+        # | `license` | `cc:license` resource |
+        # @yield evaluates additional RDF work metadata
+        # @yieldreturn [Object] ignored block result
         # @return [Sevgi::Graphics::Element] RDF element
+        # @raise [Sevgi::ArgumentError] when an option is unknown
         def RDFWork(**kwargs, &block)
+          unknown = kwargs.keys - WORK_OPTIONS
+          ArgumentError.("Unknown RDF work options: #{unknown.join(", ")}") unless unknown.empty?
+
           RDF do
             Element(:"cc:Work", "rdf:about": "") do
               Element(:"dc:format", "image/svg+xml")
@@ -104,7 +177,6 @@ module Sevgi
             end
           end
         end
-        # rubocop:enable Metrics/MethodLength
       end
     end
   end

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

@@ -10,6 +10,8 @@ module Sevgi
         class Renderer
           # Default renderer options.
           DEFAULTS = {indent: "  ", linelength: 140, style: :hybrid}.freeze
+          STYLES = %i[hybrid inline block].freeze
+          SVG_NAMESPACE = "http://www.w3.org/2000/svg"
 
           # Attribute rendering strategies.
           # @api private
@@ -22,7 +24,7 @@ module Sevgi
               # @param depth [Integer] element depth
               # @return [void]
               def attributes(element, depth)
-                attributes_block(element, depth, element.attributes.to_xml_lines)
+                attributes_block(element, depth, element.attributes.send(:xml_lines))
               end
             end
 
@@ -34,7 +36,7 @@ module Sevgi
               # @param depth [Integer] element depth
               # @return [void]
               def attributes(element, depth)
-                if attributes_as_block?(lines = element.attributes.to_xml_lines, depth)
+                if attributes_as_block?(lines = element.attributes.send(:xml_lines), depth)
                   attributes_block(element, depth, lines)
                 else
                   attributes_inline(element, depth, lines)
@@ -66,7 +68,7 @@ module Sevgi
               # @param depth [Integer] element depth
               # @return [void]
               def attributes(element, depth)
-                attributes_inline(element, depth, element.attributes.to_xml_lines)
+                attributes_inline(element, depth, element.attributes.send(:xml_lines))
               end
             end
           end
@@ -77,7 +79,13 @@ module Sevgi
           ELEMENTS_WITH_BLOCK_CONTENT = %i[style].freeze
           SEPARATOR = "\n"
 
-          private_constant :ELEMENTS_WITH_INLINE_CONTENT, :ELEMENTS_WITH_BLOCK_CONTENT, :SEPARATOR
+          private_constant(
+            :ELEMENTS_WITH_INLINE_CONTENT,
+            :ELEMENTS_WITH_BLOCK_CONTENT,
+            :SEPARATOR,
+            :STYLES,
+            :SVG_NAMESPACE
+          )
 
           # @return [Sevgi::Graphics::Element] root element
           attr_reader :root
@@ -161,10 +169,10 @@ module Sevgi
           #   @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
+          #   @raise [Sevgi::ArgumentError] when an option is unknown, malformed, missing, or unsupported
           def initialize(root, **)
             @root = root
-            @options = DEFAULTS.merge(**)
+            @options = self.class.send(:validate, **)
             @output = []
             @inlines = Inlines.new
 
@@ -176,16 +184,39 @@ module Sevgi
           #   @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
+          #   @raise [Sevgi::ArgumentError] when options, preambles, names, attributes, or content are invalid XML
           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
+          # @raise [Sevgi::ArgumentError] when options, names, attributes, or content are invalid XML
           def self.fragment(root, **options) = new(root, **options).call
 
+          def self.validate(**options)
+            options = DEFAULTS.merge(options)
+            unknown = options.keys - DEFAULTS.keys
+            ArgumentError.("Unknown renderer options: #{unknown.join(", ")}") unless unknown.empty?
+
+            indent = options[:indent]
+            unless indent.is_a?(::String) && /\A[\t\n\r ]*\z/.match?(indent)
+              ArgumentError.("Renderer indent must contain only XML whitespace")
+            end
+
+            options[:indent] = XML.text(indent, context: "Renderer indent")
+            linelength = options[:linelength]
+            unless linelength.is_a?(::Integer) && linelength >= 0
+              ArgumentError.("Renderer linelength must be a non-negative Integer")
+            end
+
+            ArgumentError.("Unrecognized style: #{options[:style]}") unless STYLES.include?(options[:style])
+
+            options.freeze
+          end
+
+          private_class_method :validate
+
           # Appends rendered lines to the output buffer.
           # @param depth [Integer, nil] indentation depth
           # @param lines [Array<String>] rendered lines
@@ -199,8 +230,9 @@ module Sevgi
           # Renders the document.
           # @param preambles [Array<String>] preamble lines
           # @return [String] SVG source
+          # @raise [Sevgi::ArgumentError] when a preamble or rendered value is not valid XML text
           def call(*preambles)
-            output.append(preambles) unless preambles.empty?
+            output.append(preambles.map { XML.text(it, context: "XML preamble") }) unless preambles.empty?
 
             root.Traverse(
               0,
@@ -234,8 +266,6 @@ module Sevgi
           end
 
           def build
-            ArgumentError.("Missing style") unless options[:style]
-
             case options[:style]
             when :hybrid
               extend(Attributes::Hybrid)
@@ -243,8 +273,6 @@ module Sevgi
               extend(Attributes::Inline)
             when :block
               extend(Attributes::Block)
-            else
-              ArgumentError.("Unrecognized style: #{options[:style]}")
             end
 
             unclosed
@@ -254,10 +282,29 @@ module Sevgi
             element.children.empty? && element.contents.empty?
           end
 
+          def block_content?(element)
+            return false unless ELEMENTS_WITH_BLOCK_CONTENT.include?(element.name)
+
+            namespace = default_namespace(element)
+            namespace.nil? || namespace.to_s.empty? || namespace == SVG_NAMESPACE
+          end
+
           def closed = @closed = true
 
           def closed? = @closed.tap { unclosed }
 
+          def default_namespace(element)
+            current = element
+
+            while current.is_a?(Element)
+              return current.attributes[:xmlns] if current.attributes.has?(:xmlns)
+
+              current = current.parent
+            end
+
+            nil
+          end
+
           def contents(element, depth)
             return if element.contents.empty?
 
@@ -272,10 +319,10 @@ module Sevgi
           def floating?(element) = element.Is?(:_)
 
           def inline_content?(element)
-            return false if ELEMENTS_WITH_BLOCK_CONTENT.include?(element.name)
+            return false if block_content?(element)
             return false if floating?(element)
 
-            element.contents.size == 1 || ELEMENTS_WITH_INLINE_CONTENT.include?(element.name)
+            element.contents.any? || ELEMENTS_WITH_INLINE_CONTENT.include?(element.name)
           end
 
           def indent(depth)
@@ -284,7 +331,7 @@ module Sevgi
 
           def join
             inlines.join(output, indent: options[:indent], separator: SEPARATOR)
-            output.join(SEPARATOR)
+            XML.text(output.join(SEPARATOR), context: "SVG output")
           end
 
           def render_enter(element, depth)
@@ -307,6 +354,7 @@ module Sevgi
           end
 
           def unclosed = @closed = false
+
         end
 
         private_constant :Renderer
@@ -315,18 +363,39 @@ module Sevgi
         #   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.
+        #   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)
         #   @param options [Hash] renderer options
+        #   @option options [String] :indent ("  ") XML-whitespace indentation unit
+        #   @option options [Integer] :linelength (140) non-negative line length that switches hybrid attributes to block
+        #     style
+        #   @option options [Symbol] :style (:hybrid) attribute layout: `:hybrid`, `:inline`, or `:block`
         #   @return [String] SVG source
-        #   @raise [Sevgi::ArgumentError] when style is missing or unsupported
+        #   @raise [Sevgi::ArgumentError] when options, preambles, names, attributes, or content are invalid XML
         def Render(**) = Renderer.(self, **)
 
         # Renders only this element's children.
         # Child render output omits document preambles and preserves each child's text whitespace and inline
         # mixed-content formatting.
+        # @example Render child fragments with block-style attributes
+        #   Sevgi::Graphics.SVG(:minimal) { rect id: "one" }.RenderChildren(style: :block, indent: "\t")
         # @param separator [String] separator between child documents
+        # @param options [Hash] renderer options applied to every child fragment
+        # @option options [String] :indent ("  ") XML-whitespace indentation unit
+        # @option options [Integer] :linelength (140) non-negative line length that switches hybrid attributes to block
+        #   style
+        # @option options [Symbol] :style (:hybrid) attribute layout: `:hybrid`, `:inline`, or `:block`
         # @return [String] rendered child fragments
-        def RenderChildren(separator = "\n\n") = children.map { Renderer.fragment(it) }.join(separator)
+        # @raise [Sevgi::ArgumentError] when separator, options, or rendered child data is invalid
+        def RenderChildren(separator = "\n\n", **options)
+          ArgumentError.("SVG fragment separator must be a String") unless separator.is_a?(::String)
+
+          separator = XML.text(separator, context: "SVG fragment separator")
+          Renderer.send(:validate, **options)
+          children.map { Renderer.fragment(it, **options) }.join(separator)
+        end
       end
     end
   end

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

@@ -8,43 +8,96 @@ module Sevgi
       # DSL helpers for writing rendered SVG output.
       module Save
         # Default SVG extension.
+        # @api private
         EXT = ".svg"
 
+        private_constant :EXT
+
+        # Change-aware file writer with optional backup support.
+        # @api private
+        class Writer
+          # Writes content when it differs from the destination.
+          # @param path [String] expanded output path
+          # @param content [String] rendered content
+          # @param backup_suffix [String, nil] suffix used for an existing-file backup
+          # @yield [content] optionally normalizes old and new content for change detection
+          # @yieldparam content [String] old or new content
+          # @yieldreturn [String] normalized content
+          # @return [String, nil] expanded path when written, otherwise nil
+          # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+          def self.call(path, content, backup_suffix: nil, &filter)
+            output = "#{content.chomp}\n"
+
+            return unless F.changed?(path, output, &filter)
+
+            ::FileUtils.mkdir_p(::File.dirname(path))
+            if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
+              ::FileUtils.cp(path, "#{path}#{backup_suffix}")
+            end
+
+            path.tap { ::File.write(path, output) }
+          end
+        end
+
+        private_constant :Writer
+
         # 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)
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @return [nil]
+        # @raise [Sevgi::ArgumentError] when a render option or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Out(**kwargs)
+          F.out(self.(**kwargs))
         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
+        # 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.
+        # 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 == 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
         # @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)
-
-          if path
-            ::File.directory?(path) ? ::File.join(path, ::File.basename(default)) : path
-          else
-            default
-          end => path
-
-          ::FileUtils.mkdir_p(::File.dirname(path))
-          if backup_suffix && !backup_suffix.empty? && ::File.exist?(path)
-            ::FileUtils.cp(path, "#{path}#{backup_suffix}")
-          end
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when a selected path/default, render option, or XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination or backup cannot be created, read, or written
+        # @see Sevgi::Graphics::Document::Proto#call
+        def Save(path = nil, default: nil, backup_suffix: nil, **kwargs, &filter)
+          default = F.subext(EXT, caller_locations(1..1).first.path) if default.nil?
+          path = Path.resolve(path, default:, context: "Save")
 
-          Write(path, &filter)
+          Writer.(path, self.(**kwargs), backup_suffix:, &filter)
         end
 
         # Writes rendered SVG to a path.
-        # @param path [String] output path
-        # @param kwargs [Hash] render options
-        # @return [Object] F.out return value
+        # Missing parent directories are created. Unlike {#Save}, a directory is not treated as a request for a default
+        # file name.
+        # @param path [String, #to_path] output file path
+        # @param kwargs [Hash] pre-render and renderer options accepted by {Sevgi::Graphics::Document::Proto#call}
+        # @yield [content] optionally normalizes old and new content for change detection
+        # @yieldparam content [String] old or new SVG source
+        # @yieldreturn [String] normalized SVG source
+        # @return [String, nil] expanded path when written, or nil when unchanged
+        # @raise [Sevgi::ArgumentError] when path, a render option, or an XML-bound value is invalid
+        # @raise [Sevgi::ValidationError] when validation is enabled and the document violates the SVG standard
+        # @raise [Sevgi::Graphics::LintError] when linting is enabled and the document has structural conflicts
+        # @raise [SystemCallError] when the destination cannot be read or written
+        # @see Sevgi::Graphics::Document::Proto#call
         def Write(path, **kwargs, &filter)
-          F.out(self.(**kwargs), path, &filter)
+          path = Path.(path, context: "Write path")
+          ArgumentError.("Write path must name a file") if ::File.directory?(path)
+
+          Writer.(path, self.(**kwargs), &filter)
         end
       end
     end

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

@@ -5,17 +5,89 @@ module Sevgi
     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
+        # Builds one symbol set without adding helper methods to the document DSL.
+        # @api private
+        class Expansion
+          # Creates a symbol expansion.
+          # @param receiver [Sevgi::Graphics::Element] parent element
+          # @param mod [Module] module extended with {Sevgi::Graphics::Module}
+          # @return [void]
+          def initialize(receiver, mod)
+            @receiver = receiver
+            @mod = mod
+          end
+
+          # Builds a defs container and populates it from the callable module.
+          # @param args [Array<Object>] callable positional arguments
+          # @param attributes [Hash] defs attributes
+          # @param ids [#call, nil] symbol id mapper
+          # @param kwargs [Hash] callable keyword arguments
+          # @param block [Proc, nil] callable block argument
+          # @return [Sevgi::Graphics::Element] defs element
+          # @raise [Sevgi::ArgumentError] when an input channel is invalid
+          def call(*args, attributes:, ids:, **kwargs, &block)
+            methods = Graphics::Module.__send__(:callables, @mod)
+            ArgumentError.("Defs attributes must be a Hash") unless attributes.is_a?(::Hash)
+            ArgumentError.("Symbol ids must respond to call") if ids && !ids.respond_to?(:call)
+
+            defaults = @mod.name ? {id: F.demodulize(@mod.name).to_sym} : {}
+            attributes = Attribute.defaults(attributes, **defaults)
+            @args, @kwargs, @block = args, kwargs, block
+            @receiver.defs(**attributes).tap { populate(it, methods, ids) }
+          end
+
+          private
+
+          # Adds bases and symbols to a defs element.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param methods [Array<UnboundMethod>] callable methods
+          # @param ids [#call, nil] symbol id mapper
+          # @return [void]
+          def populate(defs, methods, ids)
+            context = Graphics::Module.__send__(:context, @mod, defs)
+            Graphics::Module.__send__(:bases, @mod).each { context.instance_exec(&it) }
+            methods.each { draw(defs, it, ids) }
+          end
+
+          # Adds one callable symbol.
+          # @param defs [Sevgi::Graphics::Element] defs element
+          # @param method [UnboundMethod] callable method
+          # @param ids [#call, nil] symbol id mapper
+          # @return [Object, nil] callable return value
+          def draw(defs, method, ids)
+            name = method.name
+            symbol = defs.symbol(id: ids ? ids.call(name) : name.to_s.tr("_", "-"))
+            symbol.title(name.to_s.split("_").map(&:capitalize).join(" "))
+            context = Graphics::Module.__send__(:context, @mod, symbol)
+            Graphics::Module.__send__(:invoke, context, symbol, [method], *@args, **@kwargs, &@block)
+          end
+        end
+
+        private_constant :Expansion
+
+        # 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
-        # @param kwargs [Hash] defs attributes
+        # Base blocks run once in the defs element before symbols are created. Positional arguments, keyword arguments,
+        # and the block are forwarded to each callable.
+        # @example Expand named drawing methods into reusable symbols
+        #   icons = Module.new do
+        #     extend Sevgi::Graphics::Module
+        #     def dot = circle r: 2
+        #     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 ids [#call, nil] optional callable mapping each method name to a symbol id
+        # @param kwargs [Hash] callable keyword arguments
+        # @yield forwarded to each callable
+        # @yieldreturn [Object] callable-defined block result
         # @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("-")
-            title(name.to_s.split("_").map(&:capitalize).join(" "))
-          end
+        # @raise [Sevgi::ArgumentError] when mod is not a callable drawing module, attributes is not a Hash, or ids is
+        #   not callable
+        def Symbols(mod, *args, attributes: {}, ids: nil, **kwargs, &block)
+          Expansion.new(self, mod).call(*args, attributes:, ids:, **kwargs, &block)
         end
       end
     end