sevgi-standard 0.73.2 → 0.94.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd86945f53c28030148a5d7e40a05c370ea9743f92cf1c264f3c30741d65baa8
-  data.tar.gz: d4012c0190f449a989c10f35d60153c397dabd9536d5567caa3956c1e3f0db68
+  metadata.gz: 032a1a8f609e2cebf4de52c844f69cdfc13504a438c08042aff5dde09ef0b331
+  data.tar.gz: 8aa466073442ec8062aa48468e7274e7e9d275558a8be154cf26fce32c121d0d
 SHA512:
-  metadata.gz: 65a9c7367b4ebc2e34fe647d71cfe50ee0038ab3acdf688a2e5460d9bd500677ca93c91daa63c08e1b958c6a6b993e864cca65ef0ee38c6bd61b78fbb532846f
-  data.tar.gz: 0b787afc81c3edf324bc272c7d25d22ff7a60d05b48fc8708981dc5ae2e8c6587a178b8a35cb9fba6ca2dd2edc4edc889190ded91a488aa47e007d70272a5d8d
+  metadata.gz: 4756ece8ebbcf5d7d971d27e9711ba116652378f271d23bcc543e19a28eae94cdd47a51d90489b79233166a1f9e9adaf0e446f4a43d73d90a6423aad6074d3c6
+  data.tar.gz: bec85c8ec04964a3e44e3d780d4b22f61e87f8faef3fbebad5b95144dbe639a76a4d5373212203e123ce57d7abb441b785d904d2f6b526a4e2e46947e1e99334

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+Sevgi Standard follows the root Sevgi release notes:
+https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/LICENSE

@@ -0,0 +1,5 @@
+Sevgi Standard is distributed under the GNU General Public License v3.0 or later.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+Full project license: https://github.com/roktas/sevgi/blob/main/LICENSE

data/README.md

@@ -0,0 +1,37 @@
+# Sevgi Standard
+
+SVG element, attribute, and conformance data used by Sevgi validation.
+
+## Install
+
+```sh
+gem install sevgi-standard
+```
+
+## Require
+
+```ruby
+require "sevgi/standard"
+```
+
+## Example
+
+```ruby
+Sevgi::Standard.element?(:rect)
+Sevgi::Standard.attribute?(:width)
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies Ruby 3.4 and the current development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+None beyond Ruby and this gem's Ruby dependencies.
+
+## Links
+
+- Documentation: https://sevgi.roktas.dev
+- API documentation: https://www.rubydoc.info/gems/sevgi-standard
+- Source: https://github.com/roktas/sevgi/tree/main/standard
+- Changelog: https://github.com/roktas/sevgi/blob/main/CHANGELOG.md

data/lib/sevgi/standard/conform.rb

@@ -2,22 +2,43 @@
 
 module Sevgi
   module Standard
+    # Validates one SVG element usage against the standard data.
+    # @api private
     class Conform
       require_relative "model"
 
-      attr_reader :element, :spec
+      # @return [Symbol] SVG element name
+      attr_reader :element
 
+      # @return [Hash] expanded standard specification for the element
+      attr_reader :spec
+
+      # Builds a validator for one SVG element.
+      # @param element [String, Symbol] SVG element name
+      # @return [void]
+      # @raise [Sevgi::ArgumentError] when element is not a valid public name
+      # @raise [Sevgi::InvalidElementsError] when the element is unknown
+      # @raise [Sevgi::PanicError] when the element model is missing or unimplemented
       def initialize(element)
+        element = Name.normalize!(element, context: "element")
+
         InvalidElementsError.(element) unless (@spec = Specification[@element = element])
 
-        raise ModelError, "No model specified: #{element}" unless spec[:model]
-        raise ModelError, "Model unimplemented: #{spec[:model]}" unless Model.const_defined?(spec[:model])
+        PanicError.("No model specified: #{element}") unless spec[:model]
+        PanicError.("Model unimplemented: #{spec[:model]}") unless Model.const_defined?(spec[:model])
 
         extend(Model.const_get(spec[:model]))
 
-        raise NoMethodError, "#{self.class}#apply must be implemented" unless respond_to?(:apply)
+        PanicError.("#{self.class}#apply must be implemented") unless respond_to?(:apply)
       end
 
+      # Validates one usage of the configured SVG element.
+      # @param attributes [Array<String, Symbol>, nil] attribute names used by the element
+      # @param cdata [String, nil] character data content
+      # @param elements [Array<String, Symbol>, nil] child element names
+      # @return [Boolean] true when the usage conforms
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
+      # @raise [Sevgi::ValidationError] when the usage violates the standard data
       def call(attributes: nil, cdata: nil, elements: nil)
         if attributes
           unrecognized = attributes - spec[:attributes]
@@ -32,7 +53,20 @@ module Sevgi
 
       @cache = {}
 
+      # Validates one SVG element usage, using cached element validators.
+      # @param element [String, Symbol] SVG element name
+      # @param attributes [Array<String, Symbol>, nil] attribute names used by the element
+      # @param cdata [String, nil] character data content
+      # @param elements [Array<String, Symbol>, nil] child element names
+      # @return [Boolean] true when the usage conforms or the element is ignored
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
+      # @raise [Sevgi::ValidationError] when the usage violates the standard data
+      # @raise [Sevgi::PanicError] when the standard data refers to an invalid model
       def self.call(element, attributes: nil, cdata: nil, elements: nil)
+        element = Name.normalize!(element, context: "element")
+        attributes = Name.list!(attributes, context: "attribute")
+        elements = Name.list!(elements || [], context: "element")
+
         Element.ignore?(element) or
           (@cache[element] ||= new(element)).call(
             attributes: Attribute.concerns(attributes),

data/lib/sevgi/standard/data/attribute.rb

@@ -483,7 +483,6 @@ module Sevgi
         Deprecated: %i[
           accent-height
           alphabetic
-          amplitude
           arabic-form
           ascent
           attributeType
@@ -492,12 +491,29 @@ module Sevgi
         ]
       )
 
+      RESERVED_NAMESPACE_PREFIXES = %w[xlink: xml:].freeze
+      private_constant :RESERVED_NAMESPACE_PREFIXES
+
+      # Reports whether an attribute name should be ignored by standard validation.
+      # @param attribute [String, Symbol, Object] candidate attribute name
+      # @return [Boolean] true for valid private, data, xmlns, or foreign namespaced attributes
       def ignore?(attribute)
-        attribute.start_with?("_") ||
-          attribute == :xmlns ||
-          attribute.start_with?("data-") ||
-          (attribute.to_s.include?(":") && !attribute.start_with?("xlink:") && !attribute.start_with?("xml:"))
+        return false unless attribute.is_a?(::String) || attribute.is_a?(::Symbol)
+
+        name = attribute.to_s
+
+        Name.valid?(name) && ignored_name?(name)
       end
+
+      def ignored_name?(name)
+        name.start_with?("_") || name == "xmlns" || name.start_with?("data-") || foreign_namespace?(name)
+      end
+
+      def foreign_namespace?(name)
+        name.include?(":") && RESERVED_NAMESPACE_PREFIXES.none? { name.start_with?(it) }
+      end
+
+      private_class_method :foreign_namespace?, :ignored_name?
     end
   end
 end

data/lib/sevgi/standard/data/color.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-# Recognized color keyword names: https://www.w3.org/TR/2003/REC-SVG11-20030114/types.html#ColorKeywords
-
 module Sevgi
   module Standard
+    # Recognized SVG color keyword names mapped to hexadecimal RGB values.
     Color = {
       aliceblue: "#F0F8FF",
       antiquewhite: "#FAEBD7",
@@ -154,7 +153,7 @@ module Sevgi
       yellowgreen: "#9ACD32"
     }
       .tap do |color|
-        def color.valid?(name) = key?(name.to_sym)
+        def color.valid?(name) = name.respond_to?(:to_sym) && key?(name.to_sym)
 
         color.each { |name, hex| color.define_singleton_method(name) { hex } }
       end

data/lib/sevgi/standard/data/element.rb

@@ -8,6 +8,7 @@ module Sevgi
           animate
           animateMotion
           animateTransform
+          discard
           mpath
           set
         ],
@@ -146,7 +147,6 @@ module Sevgi
           linearGradient
           pattern
           radialGradient
-          solidcolor
         ],
 
         Renderable: %i[
@@ -265,8 +265,15 @@ module Sevgi
         ]
       )
 
+      # Reports whether an element name should be ignored by standard validation.
+      # @param element [String, Symbol, Object] candidate element name
+      # @return [Boolean] true for valid private or namespaced element names that Sevgi should not validate
       def ignore?(element)
-        (name = element.to_s).include?(":") || name.start_with?("_")
+        return false unless element.is_a?(::String) || element.is_a?(::Symbol)
+
+        name = element.to_s
+
+        Name.valid?(name) && (name.include?(":") || name.start_with?("_"))
       end
     end
   end

data/lib/sevgi/standard/data.rb

@@ -4,19 +4,77 @@ require_relative "data/color"
 
 module Sevgi
   module Standard
-    module Common
-      def all = @all ||= Set[*data.values.flatten.uniq.sort]
+    # Defensive copy helper for public standard-data snapshots.
+    # @api private
+    module Snapshot
+      # Returns a recursively independent copy of a value.
+      # @param value [Object] value to copy
+      # @return [Object] copied value
+      def self.copy(value)
+        case value
+        when ::Hash
+          hash(value)
+        when ::Array
+          value.map { copy(it) }
+        when ::Set
+          Set[*value.map { copy(it) }]
+        else
+          duplicate(value)
+        end
+      end
+
+      def self.hash(value) = value.to_h { |key, item| [key, copy(item)] }
+
+      def self.duplicate(value)
+        value.dup
+      rescue ::TypeError
+        value
+      end
 
+      private_class_method :duplicate, :hash
+    end
+
+    private_constant :Snapshot
+
+    # Shared set operations for SVG standard data lists.
+    # @api private
+    module Common
+      # Returns every known name in this data list.
+      # @return [Set<Symbol>] mutation-isolated set snapshot
+      def all = Snapshot.copy(@all ||= Set[*data.values.flatten.uniq.sort])
+
+      # Checks whether a name belongs to a group.
+      # @param name [Symbol] item name
+      # @param group [Symbol] group name
+      # @return [Boolean]
       def is?(name, group) = self[group].include?(name)
 
+      # Keeps names that belong to any requested group.
+      # @param names [Array<Symbol>] names to filter
+      # @param groups [Array<Symbol>] group names
+      # @return [Array<Symbol>] filtered names
       def pick(names, *groups) = names.select { |name| groups.any? { is?(name, it) } }
 
+      # Returns all names or names from selected groups.
+      # @param groups [Array<Symbol>] group names
+      # @return [Set<Symbol>] mutation-isolated selected-name snapshot
       def set(*groups) = groups.empty? ? all : Set[*data.values_at(*groups).flatten.compact.uniq.sort]
 
+      # Removes names that belong to any requested group.
+      # @param names [Array<Symbol>] names to filter
+      # @param groups [Array<Symbol>] group names
+      # @return [Array<Symbol>] filtered names
       def unpick(names, *groups) = names.reject { |name| groups.any? { is?(name, it) } }
 
+      # Removes ignored names from a list.
+      # @param names [Array<Symbol>, nil] names to filter
+      # @return [Array<Symbol>, nil] names that should be validated
       def concerns(names) = names ? names.reject { ignore?(it) } : names
 
+      # Installs low-level list helpers into data modules.
+      # @param base [Module] data module receiving helpers
+      # @return [void]
+      # @api private
       def self.extended(base) = base.extend(List)
     end
 
@@ -46,11 +104,27 @@ module Sevgi
 
       require_relative "data/specification"
 
-      def [](name) = expand(name)
+      # Returns expanded standard specification data for one element.
+      # @param name [Symbol] SVG element name
+      # @return [Hash, nil] mutation-isolated expanded specification snapshot
+      def [](name) = Snapshot.copy(expand(name))
 
+      # Reports whether a name is a data group name.
+      # @param name [Symbol] element or group name
+      # @return [Boolean]
       def group?(name) = /[[:upper:]]/.match?(name[0])
 
-      def model?(name, *models) = models.any? { (self[name] || {})[:model] == name }
+      # Checks whether an element uses one of the requested content models.
+      # @param name [String, Symbol] SVG element name
+      # @param models [Array<String, Symbol>] model names to match
+      # @return [Boolean]
+      # @raise [Sevgi::ArgumentError] when any name is not a valid public name
+      def model?(name, *models)
+        name = Name.normalize!(name, context: "element")
+        models = models.map { Name.normalize!(it, context: "model") }
+
+        models.any? { (self[name] || {})[:model] == it }
+      end
 
       private
 
@@ -58,7 +132,7 @@ module Sevgi
 
       def expand(name)
         @spec[name] ||= if data[name]
-          data[name].dup.tap do |spec|
+          data[name].transform_values { |value| value.is_a?(::Array) ? value.dup : value }.tap do |spec|
             expand_names(spec[:elements], Element.data)
             expand_names(spec[:attributes], Attribute.data)
           end
@@ -68,12 +142,12 @@ module Sevgi
       def expand_names(names, list)
         return unless names
 
-        names.replace(names.map { |name| group?(name) ? list[name] : name }.flatten)
+        names.replace(names.flat_map { |name| group?(name) ? list[name] : name }.uniq)
       end
 
       # For testing purposes
 
-      def charge = data.keys { expand(it) }
+      def charge = data.each_key { expand(it) }
 
       def flush = (@spec = {})
     end

data/lib/sevgi/standard/errors.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Sevgi
+  # Base class for SVG standard validation errors.
   class ValidationError < Error
+    # Builds a validation error with a context label and offending values.
+    # @param context [Object] validation context included in the error message
+    # @param args [Array<Object>, Object] invalid values included in the error message
+    # @return [void]
     def initialize(context, args = [])
       @context = context
       @args = Array(args)
@@ -9,8 +14,18 @@ module Sevgi
       super()
     end
 
-    def self.call(context, args = []) = raise new(context, args)
+    # Raises this validation error class.
+    # @param context [Object] validation context included in the error message
+    # @param args [Array<Object>, Object] invalid values included in the error message
+    # @return [void]
+    # @raise [Sevgi::ValidationError] always raises an instance of this class
+    def self.call(context, args = [])
+      raise new(context, args)
+    end
 
+    # Builds a validation error subclass with a fixed message fragment.
+    # @param message [String] message fragment placed after the validation context
+    # @return [Class<Sevgi::ValidationError>] validation error subclass
     def self.variant(message)
       Class.new(self) do
         define_method(:message) do
@@ -24,9 +39,14 @@ module Sevgi
     end
   end
 
+  # Raised when an element contains invalid attributes.
   InvalidAttributesError = ValidationError.variant("Invalid attribute(s)")
+  # Raised when an element contains invalid child elements.
   InvalidElementsError = ValidationError.variant("Invalid element(s)")
+  # Raised when character data appears where the SVG model forbids it.
   UnallowedCDataError = ValidationError.variant("Character data not allowed")
+  # Raised when an element contains disallowed child elements.
   UnallowedElementsError = ValidationError.variant("Element(s) not allowed")
+  # Raised when a conditional SVG content model requirement is not met.
   UnmetConditionError = ValidationError.variant("Condition unmet for the element")
 end

data/lib/sevgi/standard/internal.rb

@@ -2,13 +2,69 @@
 
 module Sevgi
   module Standard
+    # Normalizes public SVG standard names at API boundaries.
+    # @api private
+    module Name
+      PATTERN = /\A[A-Za-z_][A-Za-z0-9_.-]*(?::[A-Za-z_][A-Za-z0-9_.-]*)?\z/
+      private_constant :PATTERN
+
+      # Reports whether a string is a supported SVG-style name token.
+      # @param name [String] candidate name
+      # @return [Boolean]
+      def self.valid?(name) = !!PATTERN.match?(name)
+
+      # Normalizes one public name to the registry symbol form.
+      # @param value [String, Symbol] public name
+      # @param context [String] name context for error messages
+      # @return [Symbol] normalized name
+      # @raise [Sevgi::ArgumentError] when value is not a String or Symbol
+      # @raise [Sevgi::ArgumentError] when value is not a valid SVG-style name
+      def self.normalize!(value, context:)
+        case value
+        when ::String, ::Symbol
+          text = value.to_s
+          ArgumentError.("Invalid SVG #{context} name: #{value.inspect}") unless valid?(text)
+
+          text.to_sym
+        else
+          ArgumentError.("SVG #{context} name must be a String or Symbol: #{value.inspect}")
+        end
+      end
+
+      # Normalizes a list of public names.
+      # @param values [Array<String, Symbol>, nil] public names
+      # @param context [String] name context for error messages
+      # @return [Array<Symbol>, nil] normalized names
+      # @raise [Sevgi::ArgumentError] when any value is not a valid public name
+      def self.list!(values, context:)
+        values&.map { normalize!(it, context:) }
+      end
+    end
+
+    private_constant :Name
+
+    # Low-level import and lookup helper for static SVG standard data.
+    # @api private
     module List
+      # Looks up a data entry.
+      # @param name [Symbol] data key
+      # @return [Object, nil] stored data value
       def [](name) = data[name]
 
+      # Imports new data entries without overwriting existing keys.
+      # @param kwargs [Hash] entries to import
+      # @return [Hash] backing data hash
       def import(**kwargs) = data.merge!(kwargs.reject { |key, _| data.key?(key) })
 
+      # Reports whether a data entry exists.
+      # @param name [Symbol] data key
+      # @return [Boolean]
       def valid?(name) = data.key?(name)
 
+      # Initializes the backing data hash on extended modules.
+      # @param base [Module] module receiving list behavior
+      # @return [void]
+      # @api private
       def self.extended(base)
         super
 

data/lib/sevgi/standard/model.rb

@@ -2,8 +2,16 @@
 
 module Sevgi
   module Standard
+    # SVG content model validators used by {Conform}.
+    # @api private
     module Model
+      # Validates elements that allow only character data.
       module CDataOnly
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedElementsError] when child elements are present
         def apply(cdata:, elements:)
           _cdata = cdata
 
@@ -11,7 +19,13 @@ module Sevgi
         end
       end
 
+      # Validates elements that allow character data or selected child elements.
       module CDataOrSomeElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
         def apply(cdata:, elements:)
           _cdata = cdata
 
@@ -20,7 +34,14 @@ module Sevgi
         end
       end
 
+      # Validates empty elements.
       module NoneElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when child elements are present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -28,7 +49,14 @@ module Sevgi
         end
       end
 
+      # Validates elements that allow selected child elements but no character data.
       module SomeElements
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -37,8 +65,15 @@ module Sevgi
         end
       end
 
+      # Validates the special `feDiffuseLighting` content model.
       module SpecialFeDiffuseLighting
-        # Any number of Descriptive elements and exactly one FilterLightSource element, in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when required light source elements are absent
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -52,8 +87,15 @@ module Sevgi
         end
       end
 
+      # Validates the special `feSpecularLighting` content model.
       module SpecialFeSpecularLighting
-        # Exactly one FilterLightSource element first and any number of Descriptive elements in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when the first child is not a light source
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 
@@ -61,14 +103,21 @@ module Sevgi
             UnmetConditionError.(element, "Exactly one FilterLightSource element as first required")
           end
 
-          if !(unallowed = Element.unpick(elements[1..], :Descriptive)).empty? && !unallowed.empty?
+          unless (unallowed = Element.unpick(elements[1..], :Descriptive)).empty?
             UnallowedElementsError.(element, unallowed)
           end
         end
       end
 
+      # Validates the special `font-face` content model.
       module SpecialFontFace
-        # Any number of Descriptive elements and at most one font-face element in any order.
+        # Applies this content model.
+        # @param cdata [String, nil] character data content
+        # @param elements [Array<Symbol>] child element names
+        # @return [nil]
+        # @raise [Sevgi::UnallowedCDataError] when character data is present
+        # @raise [Sevgi::UnallowedElementsError] when unallowed child elements are present
+        # @raise [Sevgi::UnmetConditionError] when more than one `font-face` child is present
         def apply(cdata:, elements:)
           UnallowedCDataError.(element, cdata) if cdata
 

data/lib/sevgi/standard/version.rb

@@ -2,6 +2,7 @@
 
 module Sevgi
   module Standard
-    VERSION = "0.73.2"
+    # Current version of the Sevgi standard gem.
+    VERSION = "0.94.0"
   end
 end

data/lib/sevgi/standard.rb

@@ -11,21 +11,69 @@ require_relative "standard/conform"
 require_relative "standard/version"
 
 module Sevgi
+  # SVG standard data and validation helpers.
+  # The registry is a Sevgi compatibility set based on SVG 2 plus the split-out SVG modules and legacy entries already
+  # modeled in the bundled specifications. Supported element names must have matching specification data; abandoned or
+  # unspecified proposal entries are not exposed as supported elements.
   module Standard
     extend self
 
+    # @overload attributes(*groups)
+    #   Returns SVG attributes, optionally restricted to one or more attribute groups.
+    #   @param groups [Array<Symbol>] attribute group names
+    #   @return [Set<Symbol>] mutation-isolated attribute-name snapshot
     def attributes(...) = Attribute.set(...)
 
-    def attribute?(name) = Attribute.all.include?(name.to_sym)
+    # Reports whether an attribute name is recognized by the SVG standard data.
+    # @param name [String, Symbol] attribute name
+    # @return [Boolean]
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def attribute?(name) = Attribute.all.include?(Name.normalize!(name, context: "attribute"))
 
+    # @overload conform(element, attributes: nil, cdata: nil, elements: nil)
+    #   Validates an SVG element usage against the standard data.
+    #   @param element [String, Symbol] SVG element name
+    #   @param attributes [Array<String, Symbol>, nil] attribute names used by the element
+    #   @param cdata [String, nil] character data content
+    #   @param elements [Array<String, Symbol>, nil] child element names
+    #   @return [Boolean] true when the usage conforms
+    #   @raise [Sevgi::ArgumentError] when any name is not a String or Symbol
+    #   @raise [Sevgi::ArgumentError] when any name is not a valid SVG-style name
+    #   @raise [Sevgi::ValidationError] when the usage violates the standard data
+    #   @raise [Sevgi::PanicError] when the standard data refers to an invalid model
     def conform(...) = Conform.(...)
 
+    # @overload elements(*groups)
+    #   Returns SVG elements, optionally restricted to one or more element groups.
+    #   @param groups [Array<Symbol>] element group names
+    #   @return [Set<Symbol>] mutation-isolated element-name snapshot
     def elements(...) = Element.set(...)
 
-    def element?(name) = Element.all.include?(name.to_sym)
+    # Reports whether an element name is recognized by the SVG standard data.
+    # @param name [String, Symbol] element name
+    # @return [Boolean]
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def element?(name) = Element.all.include?(Name.normalize!(name, context: "element"))
 
+    # @overload model?(name, *models)
+    #   Checks whether an element uses one of the requested content models.
+    #   @param name [String, Symbol] SVG element name
+    #   @param models [Array<String, Symbol>] model names to match
+    #   @return [Boolean]
+    #   @raise [Sevgi::ArgumentError] when any name is not a String or Symbol
+    #   @raise [Sevgi::ArgumentError] when any name is not a valid SVG-style name
     def model?(...) = Specification.model?(...)
 
-    def [](name) = Specification[name.to_sym]
+    # Returns the expanded standard contract for an SVG element.
+    # The returned hash and nested arrays are mutation-isolated snapshots; changing them does not alter the registry.
+    # @param name [String, Symbol] SVG element name
+    # @return [Hash, nil] expanded specification snapshot, or nil when name is unknown
+    # @raise [Sevgi::ArgumentError] when name is not a String or Symbol
+    # @raise [Sevgi::ArgumentError] when name is not a valid SVG-style name
+    def specification(name) = Specification[Name.normalize!(name, context: "element")]
+
+    alias [] specification
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sevgi-standard
 version: !ruby/object:Gem::Version
-  version: 0.73.2
+  version: 0.94.0
 platform: ruby
 authors:
 - Recai Oktaş
@@ -15,20 +15,22 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.73.2
+        version: 0.94.0
 description: Validates elements and attributes according to the SVG specification.
 email: roktas@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
 - README.md
 - lib/sevgi/standard.rb
 - lib/sevgi/standard/conform.rb
@@ -56,7 +58,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0.pre.preview1
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="