structured_params 0.9.2 → 0.9.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99bd6bd346b7e55ee390e747bb9ff232aa84af52e0198b48d162b42e7caed5f8
-  data.tar.gz: b4746d75c8201e0751e1d413155697a2f23da1d0da667491749838db0a6c0c19
+  metadata.gz: 60e548d315d109b5010333626042b9b011e867ce533c38de971201e2c9d2d87a
+  data.tar.gz: d2606fcd8176f4dc916af2bf879b48545508032c4752343caf9db7f0789bb7c5
 SHA512:
-  metadata.gz: 2aef79c11cbb97312962a39869726aa7ce95ef1e1b3f29974d3d8bc1d1637487ef7cb85dbe47742866db1db9572e83999bb52095fe634247c1170cafd0ff5433
-  data.tar.gz: b2a6bce45a08f4521979084f2ecd6b20385b7aeec3794ae2cfb8bd57d6888e87ffdae4dae10a4887b07e47417afc80d256235e25bc8ce5c9c96a3316391f81ab
+  metadata.gz: e9c3970818c47a021c522d12ca409b56730d580961fb79dc6cc311da9756bdec5b971fcc4e7cc9d8a2dd611b363aa5977356e074fdf1f7bc162bfddc04287692
+  data.tar.gz: a7930657984c4554dc7b172a7d9982a6c40cfe128053efbd4afaae2a41e8839211e063b6be3b1b5022390bf70825251633c3feaf7e955363329a8f32b1e6722d

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.9.4] - 2026-05-02
+
+## What's Changed
+* Enhance array index handling and update RBS configuration by @Syati in https://github.com/Syati/structured_params/pull/16
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.3...v0.9.4
+
+## [0.9.3] - 2026-04-09
+
+## What's Changed
+* Enhance i18n support for nested attributes and update documentation by @Syati in https://github.com/Syati/structured_params/pull/15
+
+
+**Full Changelog**: https://github.com/Syati/structured_params/compare/v0.9.2...v0.9.3
+
 ## [0.9.2] - 2026-04-02
 
 ## What's Changed

data/lib/structured_params/i18n.rb

@@ -0,0 +1,141 @@
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module StructuredParams
+  # Provides i18n-aware human_attribute_name resolution for nested dot-notation
+  # attributes (e.g. "hobbies.0.name").
+  #
+  # When included in a Params subclass, overrides +human_attribute_name+ so that
+  # each segment of the path is resolved by the corresponding nested model class,
+  # ensuring that child-model translations are respected instead of falling back
+  # to the parent model's i18n context.
+  #
+  # == i18n keys
+  #
+  # You can customize how array indices and object nesting are rendered by
+  # defining the following keys in your locale file:
+  #
+  #   ja:
+  #     activemodel:
+  #       errors:
+  #         nested_attribute:
+  #           array:  "%{parent} %{index} 番目の%{child}"
+  #           object: "%{parent}の%{child}"
+  #
+  # Without these keys the defaults are (with array_index_base: 0):
+  #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
+  #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  #
+  # With array_index_base: 1 (human-friendly):
+  #   array  → "Hobbies 1 Name"
+  module I18n
+    extend ActiveSupport::Concern
+
+    class_methods do # rubocop:disable Metrics/BlockLength
+      # Override human_attribute_name to resolve nested dot-notation paths.
+      #
+      # Flat attributes (no dot) are delegated to the default ActiveModel
+      # behaviour unchanged.
+      #
+      # Example (en default, array_index_base: 0):
+      #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
+      #
+      # Example with i18n (ja) and array_index_base: 1:
+      #   human_attribute_name(:'hobbies.0.name') # => "趣味 1 番目の名前"
+      #
+      #: (Symbol | String, ?Hash[untyped, untyped]) -> String
+      def human_attribute_name(attribute, options = {})
+        parts = attribute.to_s.split('.')
+        return super if parts.length == 1
+        return super unless structured_attributes.key?(parts.first)
+
+        resolve_nested_human_attribute_name(parts, options)
+      end
+
+      private
+
+      # Walk +parts+ (e.g. ["hobbies", "0", "name"]) and build a human-readable
+      # label by delegating each segment to the appropriate nested class.
+      #
+      # Only +:locale+ is forwarded to inner +human_attribute_name+ calls.
+      # Options such as +:default+ are specific to the outer call (e.g. from
+      # +full_messages+) and must not bleed into individual segment lookups,
+      # where they would replace the segment's own translation fallback.
+      #
+      #: (Array[String], Hash[untyped, untyped]) -> String
+      def resolve_nested_human_attribute_name(parts, options)
+        label = nil
+        klass = self
+        inner_opts = options.slice(:locale)
+
+        attr_segments(parts).each do |index, attr|
+          human = klass&.human_attribute_name(attr, inner_opts) || attr.humanize
+          label = build_nested_label(label, index, human, options)
+          klass &&= klass.structured_attributes[attr]
+        end
+
+        label || parts.last.humanize
+      end
+
+      # Convert a parts array into (index_or_nil, attr) pairs.
+      #
+      #   attr_segments(["hobbies", "0", "name"]) #=> [[nil, "hobbies"], ["0", "name"]]
+      #   attr_segments(["address", "postal_code"]) #=> [[nil, "address"], [nil, "postal_code"]]
+      #
+      #: (Array[String]) -> Array[[String?, String]]
+      def attr_segments(parts)
+        index = nil
+        parts.each_with_object([]) do |part, segments|
+          if part.match?(/\A\d+\z/)
+            index = part
+          else
+            segments << [index, part]
+            index = nil
+          end
+        end
+      end
+
+      # Combine +result+ (accumulated label so far), an optional array +index+,
+      # and the new +attr_human+ into a single label string.
+      #
+      # Uses the i18n keys:
+      #   activemodel.errors.nested_attribute.array  (parent, index, child)
+      #   activemodel.errors.nested_attribute.object (parent, child)
+      #
+      # The index value passed to the i18n template is adjusted by
+      # +StructuredParams.configuration.array_index_base+:
+      #   * +0+ (default) – raw 0-based Ruby index (e.g. 0, 1, 2, …)
+      #   * +1+           – human-friendly 1-based index (e.g. 1, 2, 3, …)
+      #
+      # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
+      # explicit locale passed to human_attribute_name is honoured.
+      #
+      #: (String?, String?, String, Hash[untyped, untyped]) -> String
+      def build_nested_label(result, index, attr_human, options)
+        return attr_human if result.nil?
+
+        i18n_opts = options.slice(:locale)
+
+        if index
+          display_index = index.to_i + StructuredParams.configuration.array_index_base
+          ::I18n.t(
+            'activemodel.errors.nested_attribute.array',
+            parent: result,
+            index: display_index,
+            child: attr_human,
+            default: "#{result} #{display_index} #{attr_human}",
+            **i18n_opts
+          )
+        else
+          ::I18n.t(
+            'activemodel.errors.nested_attribute.object',
+            parent: result,
+            child: attr_human,
+            default: "#{result} #{attr_human}",
+            **i18n_opts
+          )
+        end
+      end
+    end
+  end
+end

data/lib/structured_params/params.rb

@@ -55,6 +55,7 @@ module StructuredParams
     include ActiveModel::Attributes
     include AttributeMethods
     include Validations
+    include I18n
 
     # @rbs @errors: ::StructuredParams::Errors?
 
@@ -290,9 +291,11 @@ module StructuredParams
     #: (untyped, String) -> void
     def import_structured_errors(structured_errors, prefix)
       structured_errors.each do |error|
-        # Create dotted attribute path and import normally
+        # Create dotted attribute path and import with the message already resolved
+        # in the child model's i18n context, so the parent model's locale does not
+        # override the child's translations.
         error_attribute = "#{prefix}.#{error.attribute}"
-        errors.import(error, attribute: error_attribute.to_sym)
+        errors.import(error, attribute: error_attribute.to_sym, message: error.message)
       end
     end
   end

data/lib/structured_params/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module StructuredParams
-  VERSION = '0.9.2' #: string
+  VERSION = '0.9.4' #: string
 end

data/lib/structured_params.rb

@@ -12,6 +12,7 @@ require_relative 'structured_params/version'
 require_relative 'structured_params/errors'
 require_relative 'structured_params/attribute_methods'
 require_relative 'structured_params/validations'
+require_relative 'structured_params/i18n'
 
 # types (load first for module definition)
 require_relative 'structured_params/type/object'
@@ -22,17 +23,75 @@ require_relative 'structured_params/params'
 
 # Main module
 module StructuredParams
-  # Helper method to register types
-  #: () -> void
-  def self.register_types
-    ActiveModel::Type.register(:object, StructuredParams::Type::Object)
-    ActiveModel::Type.register(:array, StructuredParams::Type::Array)
+  # Global configuration for StructuredParams.
+  #
+  # == Options
+  #
+  # +array_index_base+ (Integer, default: +0+)::
+  #   Controls how array indices are displayed in human attribute names and
+  #   error messages.
+  #
+  #   * +0+ – 0-based (raw Ruby index): "Hobbies 0 Name"
+  #   * +1+ – 1-based (human-friendly): "Hobbies 1 Name"
+  #
+  # This setting applies to both API param error messages and Form Object
+  # +full_messages+.
+  #
+  # == Example
+  #
+  #   # config/initializers/structured_params.rb
+  #   StructuredParams.configure do |config|
+  #     config.array_index_base = 1   # show "1st" instead of "0th" to users
+  #   end
+  #
+  class Configuration
+    attr_reader :array_index_base #: Integer
+
+    #: () -> void
+    def initialize
+      @array_index_base = 0
+    end
+
+    #: (Integer) -> void
+    def array_index_base=(value)
+      unless value.is_a?(Integer) && [0, 1].include?(value)
+        raise ArgumentError, "array_index_base must be 0 or 1, got: #{value.inspect}"
+      end
+
+      @array_index_base = value
+    end
   end
 
-  # Helper method to register types with custom names
-  #: (object_name: Symbol, array_name: Symbol) -> void
-  def self.register_types_as(object_name:, array_name:)
-    ActiveModel::Type.register(object_name, StructuredParams::Type::Object)
-    ActiveModel::Type.register(array_name, StructuredParams::Type::Array)
+  class << self
+    # @rbs self.@configuration: Configuration?
+
+    #: () -> Configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    #: () { (Configuration) -> void } -> void
+    def configure
+      yield configuration
+    end
+
+    #: () -> void
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Helper method to register types
+    #: () -> void
+    def register_types
+      ActiveModel::Type.register(:object, StructuredParams::Type::Object)
+      ActiveModel::Type.register(:array, StructuredParams::Type::Array)
+    end
+
+    # Helper method to register types with custom names
+    #: (object_name: Symbol, array_name: Symbol) -> void
+    def register_types_as(object_name:, array_name:)
+      ActiveModel::Type.register(object_name, StructuredParams::Type::Object)
+      ActiveModel::Type.register(array_name, StructuredParams::Type::Array)
+    end
   end
 end

data/sig/structured_params/i18n.rbs

@@ -0,0 +1,86 @@
+# Generated from lib/structured_params/i18n.rb with RBS::Inline
+
+module StructuredParams
+  # Provides i18n-aware human_attribute_name resolution for nested dot-notation
+  # attributes (e.g. "hobbies.0.name").
+  #
+  # When included in a Params subclass, overrides +human_attribute_name+ so that
+  # each segment of the path is resolved by the corresponding nested model class,
+  # ensuring that child-model translations are respected instead of falling back
+  # to the parent model's i18n context.
+  #
+  # == i18n keys
+  #
+  # You can customize how array indices and object nesting are rendered by
+  # defining the following keys in your locale file:
+  #
+  #   ja:
+  #     activemodel:
+  #       errors:
+  #         nested_attribute:
+  #           array:  "%{parent} %{index} 番目の%{child}"
+  #           object: "%{parent}の%{child}"
+  #
+  # Without these keys the defaults are (with array_index_base: 0):
+  #   array  → "<parent> <index> <child>"   (e.g. "Hobbies 0 Name")
+  #   object → "<parent> <child>"           (e.g. "Address Postal code")
+  #
+  # With array_index_base: 1 (human-friendly):
+  #   array  → "Hobbies 1 Name"
+  module I18n
+    extend ActiveSupport::Concern
+
+    # Override human_attribute_name to resolve nested dot-notation paths.
+    #
+    # Flat attributes (no dot) are delegated to the default ActiveModel
+    # behaviour unchanged.
+    #
+    # Example (en default, array_index_base: 0):
+    #   human_attribute_name(:'hobbies.0.name') # => "Hobbies 0 Name"
+    #
+    # Example with i18n (ja) and array_index_base: 1:
+    #   human_attribute_name(:'hobbies.0.name') # => "趣味 1 番目の名前"
+    #
+    # : (Symbol | String, ?Hash[untyped, untyped]) -> String
+    def human_attribute_name: (Symbol | String, ?Hash[untyped, untyped]) -> String
+
+    private
+
+    # Walk +parts+ (e.g. ["hobbies", "0", "name"]) and build a human-readable
+    # label by delegating each segment to the appropriate nested class.
+    #
+    # Only +:locale+ is forwarded to inner +human_attribute_name+ calls.
+    # Options such as +:default+ are specific to the outer call (e.g. from
+    # +full_messages+) and must not bleed into individual segment lookups,
+    # where they would replace the segment's own translation fallback.
+    #
+    # : (Array[String], Hash[untyped, untyped]) -> String
+    def resolve_nested_human_attribute_name: (Array[String], Hash[untyped, untyped]) -> String
+
+    # Convert a parts array into (index_or_nil, attr) pairs.
+    #
+    #   attr_segments(["hobbies", "0", "name"]) #=> [[nil, "hobbies"], ["0", "name"]]
+    #   attr_segments(["address", "postal_code"]) #=> [[nil, "address"], [nil, "postal_code"]]
+    #
+    # : (Array[String]) -> Array[[String?, String]]
+    def attr_segments: (Array[String]) -> Array[[ String?, String ]]
+
+    # Combine +result+ (accumulated label so far), an optional array +index+,
+    # and the new +attr_human+ into a single label string.
+    #
+    # Uses the i18n keys:
+    #   activemodel.errors.nested_attribute.array  (parent, index, child)
+    #   activemodel.errors.nested_attribute.object (parent, child)
+    #
+    # The index value passed to the i18n template is adjusted by
+    # +StructuredParams.configuration.array_index_base+:
+    #   * +0+ (default) – raw 0-based Ruby index (e.g. 0, 1, 2, …)
+    #   * +1+           – human-friendly 1-based index (e.g. 1, 2, 3, …)
+    #
+    # The +locale:+ key from +options+ is forwarded to ::I18n.t so that an
+    # explicit locale passed to human_attribute_name is honoured.
+    #
+    # : (String?, String?, String, Hash[untyped, untyped]) -> String
+    def build_nested_label: (String?, String?, String, Hash[untyped, untyped]) -> String
+  end
+end

data/sig/structured_params/params.rbs

@@ -58,6 +58,8 @@ module StructuredParams
 
     include Validations
 
+    include I18n
+
     @errors: ::StructuredParams::Errors?
 
     self.@structured_attributes: Hash[Symbol, singleton(::StructuredParams::Params)]?

data/sig/structured_params/type/array.rbs

@@ -29,6 +29,19 @@ module StructuredParams
       def serialize: (::Array[untyped]?) -> ::Array[untyped]?
 
       # Get permitted parameter names for use with Strong Parameters
+      #
+      # Returns:
+      #   - For object arrays (value_class): nested keys from the object
+      #     Example: HobbyParams with [:name, :level]
+      #     → returns [:name, :level]
+      #     → becomes { hobbies: [:name, :level] } in Params#permit_attribute_names
+      #
+      #   - For primitive arrays (value_type): empty array
+      #     Example: attribute :tags, :array, value_type: :string
+      #     → returns []
+      #     → becomes { tags: [] } in Params#permit_attribute_names
+      #     → finally used as params.permit(:name, { tags: [] })
+      #
       # : () -> ::Array[untyped]
       def permit_attribute_names: () -> ::Array[untyped]
 

data/sig/structured_params.rbs

@@ -2,6 +2,47 @@
 
 # Main module
 module StructuredParams
+  # Global configuration for StructuredParams.
+  #
+  # == Options
+  #
+  # +array_index_base+ (Integer, default: +0+)::
+  #   Controls how array indices are displayed in human attribute names and
+  #   error messages.
+  #
+  #   * +0+ – 0-based (raw Ruby index): "Hobbies 0 Name"
+  #   * +1+ – 1-based (human-friendly): "Hobbies 1 Name"
+  #
+  # This setting applies to both API param error messages and Form Object
+  # +full_messages+.
+  #
+  # == Example
+  #
+  #   # config/initializers/structured_params.rb
+  #   StructuredParams.configure do |config|
+  #     config.array_index_base = 1   # show "1st" instead of "0th" to users
+  #   end
+  class Configuration
+    attr_reader array_index_base: Integer
+
+    # : () -> void
+    def initialize: () -> void
+
+    # : (Integer) -> void
+    def array_index_base=: (Integer) -> void
+  end
+
+  self.@configuration: Configuration?
+
+  # : () -> Configuration
+  def self.configuration: () -> Configuration
+
+  # : () { (Configuration) -> void } -> void
+  def self.configure: () { (Configuration) -> void } -> void
+
+  # : () -> void
+  def self.reset_configuration!: () -> void
+
   # Helper method to register types
   # : () -> void
   def self.register_types: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: structured_params
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.4
 platform: ruby
 authors:
 - Mizuki Yamamoto
@@ -61,6 +61,7 @@ files:
 - lib/structured_params.rb
 - lib/structured_params/attribute_methods.rb
 - lib/structured_params/errors.rb
+- lib/structured_params/i18n.rb
 - lib/structured_params/params.rb
 - lib/structured_params/type/array.rb
 - lib/structured_params/type/object.rb
@@ -69,6 +70,7 @@ files:
 - sig/structured_params.rbs
 - sig/structured_params/attribute_methods.rbs
 - sig/structured_params/errors.rbs
+- sig/structured_params/i18n.rbs
 - sig/structured_params/params.rbs
 - sig/structured_params/type/array.rbs
 - sig/structured_params/type/object.rbs