whittaker_tech-midas 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 027c1179177e4e7a6c618a55e196fad98d2b617a91b7ef70a49fb8653bb983ae
-  data.tar.gz: 54a5943974b9b93be6dfed049b87566afd9c952c560f5b286e62dba46ee18d1c
+  metadata.gz: 79ce2a5c7e59f15a9ca7af2ea759c514a32fcdc67915618d01d4f1cf2c00bd9a
+  data.tar.gz: 149f3fa609b856dffdef559835f668bb47758c00262d5cb2d4517ef21f3c1892
 SHA512:
-  metadata.gz: e6bde8babeb983a210ebb849c01a407c620491be821260782b43977747d84b4c07b23e3878597d49e7e0a2421dd3aab10ffc5aa165403f35f56b152ecdcc8e4f
-  data.tar.gz: dec832c4c97ae6155a9b67ed0dade3254ea06509446855ace527b6d574018bcafa162ad9d0a5849bf68636365ef38e5627bd16639acae290c6eb58f3890f6eed
+  metadata.gz: f446717fbf1acd4e4a3648eec3aeadbaa71e6263b60e77b68e3c960cfaa10a958783888d5bfa0df53c39cbff8e4849193a173aaa423fd4e92830bd7a954c22a5
+  data.tar.gz: 538185c60138515129e23ad762985a2bed02ebb369c6c02311107a06c876f481a66df71c4d4437ff99d39d43d67974e18f81b4c172c4d50dde16945dff0b1d34

data/README.md

@@ -1,8 +1,8 @@
 # WhittakerTech::Midas
 
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](MIT-LICENSE)
-[![Ruby 3.4](https://img.shields.io/badge/ruby-3.4+-red.svg)]()
-[![Rails 7.1](https://img.shields.io/badge/rails-7.1+-crimson.svg)]()
+![Ruby 3.4](https://img.shields.io/badge/ruby-3.4+-red.svg)
+![Rails 7.1](https://img.shields.io/badge/rails-7.1+-crimson.svg)
 [![Gem Version](https://badge.fury.io/rb/whittaker_tech-midas.svg)](https://badge.fury.io/rb/whittaker_tech-midas)
 [![CI](https://github.com/WhittakerTech/midas/actions/workflows/ci.yml/badge.svg)](https://github.com/WhittakerTech/midas/actions)
 

data/app/controllers/whittaker_tech/midas/application_controller.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    class ApplicationController < ActionController::Base
-    end
-  end
+class WhittakerTech::Midas::ApplicationController < ActionController::Base
 end

data/app/helpers/whittaker_tech/midas/application_helper.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    module ApplicationHelper
-    end
-  end
+module WhittakerTech::Midas::ApplicationHelper
 end

data/app/helpers/whittaker_tech/midas/form_helper.rb

@@ -1,78 +1,74 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    # Form helper for rendering currency input fields with bank-style typing behavior.
-    #
-    # This helper provides a headless currency input that the parent application
-    # can style according to its design system. The helper only provides the
-    # behavior (via Stimulus) and basic structure.
-    #
-    # @example Basic usage (unstyled)
-    #   <%= midas_currency_field f, :price, currency_code: 'USD' %>
-    #
-    # @example With Tailwind styling
-    #   <%= midas_currency_field f, :price,
-    #         currency_code: 'USD',
-    #         input_html: { class: 'rounded-lg border-gray-300 text-right' },
-    #         wrapper_html: { class: 'mb-4' },
-    #         label: 'Product Price' %>
-    #
-    # @example With Bootstrap styling
-    #   <%= midas_currency_field f, :price,
-    #         currency_code: 'EUR',
-    #         input_html: { class: 'form-control text-end' },
-    #         wrapper_html: { class: 'mb-3' },
-    #         label: 'Price (€)' %>
-    module FormHelper
-      # Renders a currency input field with bank-style typing behavior.
-      #
-      # The field consists of:
-      # - A visible formatted input (displays dollars/euros)
-      # - A hidden input storing minor units (cents)
-      # - A hidden input storing the currency code
-      #
-      # @param form [ActionView::Helpers::FormBuilder] The form builder
-      # @param attribute [Symbol] The coin attribute name (e.g., :price, :cost)
-      # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
-      # @param options [Hash] Additional options
-      # @option options [Hash] :input_html HTML attributes for the display input
-      # @option options [Hash] :wrapper_html HTML attributes for the wrapper div
-      # @option options [Integer] :decimals Number of decimal places (default: 2)
-      # @option options [String] :label Label text (optional, no label if nil)
-      #
-      # @return [String] Rendered HTML for the currency field
-      #
-      # @example
-      #   <%= midas_currency_field f, :price,
-      #         currency_code: 'USD',
-      #         decimals: 2,
-      #         label: 'Sale Price',
-      #         wrapper_html: { class: 'form-group' },
-      #         input_html: { class: 'form-control', placeholder: '0.00' } %>
-      def midas_currency_field(form, attribute, currency_code:, **options)
-        input_html = options.fetch(:input_html, {})
-        wrapper_html = options.fetch(:wrapper_html, {})
-        decimals = options.fetch(:decimals, 2)
-        label_text = options.fetch(:label, nil)
+# Form helper for rendering currency input fields with bank-style typing behavior.
+#
+# This helper provides a headless currency input that the parent application
+# can style according to its design system. The helper only provides the
+# behavior (via Stimulus) and basic structure.
+#
+# @example Basic usage (unstyled)
+#   <%= midas_currency_field f, :price, currency_code: 'USD' %>
+#
+# @example With Tailwind styling
+#   <%= midas_currency_field f, :price,
+#         currency_code: 'USD',
+#         input_html: { class: 'rounded-lg border-gray-300 text-right' },
+#         wrapper_html: { class: 'mb-4' },
+#         label: 'Product Price' %>
+#
+# @example With Bootstrap styling
+#   <%= midas_currency_field f, :price,
+#         currency_code: 'EUR',
+#         input_html: { class: 'form-control text-end' },
+#         wrapper_html: { class: 'mb-3' },
+#         label: 'Price (€)' %>
+module WhittakerTech::Midas::FormHelper
+  # Renders a currency input field with bank-style typing behavior.
+  #
+  # The field consists of:
+  # - A visible formatted input (displays dollars/euros)
+  # - A hidden input storing minor units (cents)
+  # - A hidden input storing the currency code
+  #
+  # @param form [ActionView::Helpers::FormBuilder] The form builder
+  # @param attribute [Symbol] The coin attribute name (e.g., :price, :cost)
+  # @param currency_code [String] ISO 4217 currency code (e.g., 'USD', 'EUR')
+  # @param options [Hash] Additional options
+  # @option options [Hash] :input_html HTML attributes for the display input
+  # @option options [Hash] :wrapper_html HTML attributes for the wrapper div
+  # @option options [Integer] :decimals Number of decimal places (default: 2)
+  # @option options [String] :label Label text (optional, no label if nil)
+  #
+  # @return [String] Rendered HTML for the currency field
+  #
+  # @example
+  #   <%= midas_currency_field f, :price,
+  #         currency_code: 'USD',
+  #         decimals: 2,
+  #         label: 'Sale Price',
+  #         wrapper_html: { class: 'form-group' },
+  #         input_html: { class: 'form-control', placeholder: '0.00' } %>
+  def midas_currency_field(form, attribute, currency_code:, **options)
+    input_html = options.fetch(:input_html, {})
+    wrapper_html = options.fetch(:wrapper_html, {})
+    decimals = options.fetch(:decimals, 2)
+    label_text = options.fetch(:label, nil)
 
-        # Get current value if coin exists
-        resource = form.object
-        coin = resource.public_send(attribute) if resource.respond_to?(attribute)
-        current_minor = coin&.currency_minor || 0
+    # Get current value if coin exists
+    resource = form.object
+    coin = resource.public_send(attribute) if resource.respond_to?(attribute)
+    current_minor = coin&.currency_minor || 0
 
-        render partial: 'whittaker_tech/midas/shared/currency_field',
-               locals: {
-                 form: form,
-                 attribute: attribute,
-                 currency_code: currency_code,
-                 current_minor: current_minor,
-                 decimals: decimals,
-                 input_html: input_html,
-                 wrapper_html: wrapper_html,
-                 label_text: label_text
-               }
-      end
-    end
+    render partial: 'whittaker_tech/midas/shared/currency_field',
+           locals: {
+             form: form,
+             attribute: attribute,
+             currency_code: currency_code,
+             current_minor: current_minor,
+             decimals: decimals,
+             input_html: input_html,
+             wrapper_html: wrapper_html,
+             label_text: label_text
+           }
   end
 end

data/app/jobs/whittaker_tech/midas/application_job.rb

@@ -1,6 +1,2 @@
-module WhittakerTech
-  module Midas
-    class ApplicationJob < ActiveJob::Base
-    end
-  end
+class WhittakerTech::Midas::ApplicationJob < ActiveJob::Base
 end

data/app/mailers/whittaker_tech/midas/application_mailer.rb

@@ -1,8 +1,4 @@
-module WhittakerTech
-  module Midas
-    class ApplicationMailer < ActionMailer::Base
-      default from: 'from@example.com'
-      layout 'mailer'
-    end
-  end
+class WhittakerTech::Midas::ApplicationMailer < ActionMailer::Base
+  default from: 'from@example.com'
+  layout 'mailer'
 end

data/app/models/concerns/whittaker_tech/midas/bankable.rb

@@ -1,189 +1,203 @@
 # frozen_string_literal: true
 
-module WhittakerTech
-  module Midas
-    # The Bankable module provides currency and monetary value management functionality
-    # for Active Record models. It allows models to have associated monetary values
-    # (coins) with different currencies and provides convenient methods for setting,
-    # retrieving, and formatting these values.
-    #
-    # When included in a model, Bankable automatically sets up a polymorphic association
-    # to the Midas::Coin model and provides class methods to define specific monetary
-    # attributes.
-    #
-    # @example Basic usage
-    #   class Product < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coin :price
-    #   end
-    #
-    #   # Create and set a price
-    #   product = Product.create!
-    #   product.set_price(amount: 29.99, currency_code: 'USD')
-    #
-    #   # Access the price
-    #   product.price          # => Coin object
-    #   product.price_amount   # => Money object
-    #   product.price_format   # => "$29.99"
-    #   product.price_in(:eur) # => "€26.85" (if exchange rates available)
-    #
-    # @example Multiple coins
-    #   class Invoice < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coins :subtotal, :tax, :total
-    #   end
-    #
-    # @example Custom dependency handling
-    #   class Order < ApplicationRecord
-    #     include WhittakerTech::Midas::Bankable
-    #
-    #     has_coin :deposit, dependent: :nullify
-    #   end
-    #
-    # == Associations Created
-    #
-    # When included, the module automatically creates:
-    # - `midas_coins`: A polymorphic has_many association to all Coin records
-    #   associated with this model instance
-    #
-    # == Methods Created by has_coin
-    #
-    # For each coin defined with `has_coin :name`, the following methods are created:
-    #
-    # - `name`: Returns the associated Coin object
-    # - `name_amount`: Returns the Money object representing the amount
-    # - `name_format`: Returns a formatted string representation of the amount
-    # - `name_in(currency)`: Returns the amount converted to the specified currency
-    # - `set_name(amount:, currency_code:)`: Sets the coin value with the given amount and currency
-    #
-    # == Supported Amount Types
-    #
-    # The `set_*` methods accept amounts in various formats:
-    # - Money objects: Used directly for cents value
-    # - Integer: Treated as cents/minor currency units
-    # - Numeric: Converted to cents using currency-specific decimal places
+# The Bankable module provides currency and monetary value management functionality
+# for Active Record models. It allows models to have associated monetary values
+# (coins) with different currencies and provides convenient methods for setting,
+# retrieving, and formatting these values.
+#
+# When included in a model, Bankable automatically sets up a polymorphic association
+# to the Midas::Coin model and provides class methods to define specific monetary
+# attributes.
+#
+# @example Basic usage
+#   class Product < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coin :price
+#   end
+#
+#   # Create and set a price
+#   product = Product.create!
+#   product.set_price(amount: 29.99, currency_code: 'USD')
+#
+#   # Access the price
+#   product.price          # => Coin object
+#   product.price_amount   # => Money object
+#   product.price_format   # => "$29.99"
+#
+# @example Multiple coins
+#   class Invoice < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coins :subtotal, :tax, :total
+#   end
+#
+# @example Custom dependency handling
+#   class Order < ApplicationRecord
+#     include WhittakerTech::Midas::Bankable
+#
+#     has_coin :deposit, dependent: :nullify
+#   end
+#
+# == Associations Created
+#
+# When included, the module automatically creates:
+# - `midas_coins`: A polymorphic has_many association to all Coin records
+#   associated with this model instance
+#
+# == Methods Created by has_coin
+#
+# For each coin defined with `has_coin :name`, the following methods are created:
+#
+# - `name`: Returns the associated Coin object
+# - `name_amount`: Returns the Money object representing the amount
+# - `name_format`: Returns a formatted string representation of the amount
+# - `set_name(amount:, currency_code:)`: Sets the coin value with the given amount and currency
+#
+# == Supported Amount Types
+#
+# The `set_*` methods accept amounts in various formats:
+# - Money objects: Used directly for cents value
+# - Integer: Treated as cents/minor currency units
+# - Numeric: Converted to cents using currency-specific decimal places
+#
+# == Currency Configuration
+#
+# The module uses I18n for currency-specific configuration:
+# - `midas.ui.currencies.<ISO_CODE>.decimal_count`: Decimal places for specific currency
+# - `midas.ui.defaults.decimal_count`: Default decimal places (defaults to 2)
+#
+# == Thread Safety
+#
+# This module is designed to be thread-safe when used with Rails' standard
+# Active Record patterns.
+#
+# See also: `WhittakerTech::Midas::Coin`
+# @since 0.1.0
+module WhittakerTech::Midas::Bankable
+  extend ActiveSupport::Concern
+
+  included do
+    has_many :midas_coins,
+             as: :resource,
+             class_name: 'WhittakerTech::Midas::Coin',
+             dependent: :destroy
+  end
+
+  class_methods do
+    # Defines multiple coin attributes at once.
     #
-    # == Currency Configuration
+    # @param names [Array<Symbol>] The names of the coin attributes to define
+    # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
+    #   (:destroy, :delete_all, :nullify, :restrict_with_exception, :restrict_with_error)
     #
-    # The module uses I18n for currency-specific configuration:
-    # - `midas.ui.currencies.{ISO_CODE}.decimal_count`: Decimal places for specific currency
-    # - `midas.ui.defaults.decimal_count`: Default decimal places (defaults to 2)
+    # @example
+    #   has_coins :price, :cost, :tax
+    #   has_coins :deposit, :refund, dependent: :nullify
+    def has_coins(*names, dependent: :destroy)
+      names.each { |name| has_coin(name, dependent:) }
+    end
+
+    # Defines a single coin attribute with associated methods and database relationship.
     #
-    # == Thread Safety
+    # This method creates:
+    # - A has_one association to the Coin model
+    # - Getter and setter methods for the coin
+    # - Helper methods for amount access and formatting
     #
-    # This module is designed to be thread-safe when used with Rails' standard
-    # Active Record patterns.
+    # @param name [Symbol] The name of the coin attribute
+    # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
     #
-    # @see WhittakerTech::Midas::Coin
-    # @since 0.1.0
-    module Bankable
-      extend ActiveSupport::Concern
-
-      included do
-        has_many :midas_coins,
-                 as: :resource,
-                 class_name: 'WhittakerTech::Midas::Coin',
-                 dependent: :destroy
-      end
+    # @example
+    #   has_coin :price
+    #   has_coin :refundable_deposit, dependent: :nullify
+    def has_coin(name, dependent: :destroy)
+      label = name.to_s
+      assoc_name = :"#{name}_coin"
 
-      class_methods do
-        # Defines multiple coin attributes at once.
-        #
-        # @param names [Array<Symbol>] The names of the coin attributes to define
-        # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
-        #   (:destroy, :delete_all, :nullify, :restrict_with_exception, :restrict_with_error)
-        #
-        # @example
-        #   has_coins :price, :cost, :tax
-        #   has_coins :deposit, :refund, dependent: :nullify
-        def has_coins(*names, dependent: :destroy)
-          names.each { |name| has_coin(name, dependent:) }
-        end
-
-        # Defines a single coin attribute with associated methods and database relationship.
-        #
-        # This method creates:
-        # - A has_one association to the Coin model
-        # - Getter and setter methods for the coin
-        # - Helper methods for amount access and formatting
-        #
-        # @param name [Symbol] The name of the coin attribute
-        # @param dependent [Symbol] The dependency behavior when the parent record is destroyed
-        #
-        # @example
-        #   has_coin :price
-        #   has_coin :refundable_deposit, dependent: :nullify
-        def has_coin(name, dependent: :destroy)
-          label = name.to_s
-          assoc_name = :"#{name}_coin"
-
-          has_one assoc_name,
-                  -> { where(resource_label: label) },
-                  as: :resource,
-                  class_name: 'WhittakerTech::Midas::Coin',
-                  dependent: dependent
-
-          define_methods(name, label, assoc_name)
-        end
-
-        def define_methods(name, label, assoc_name)
-          define_method(name) { public_send(assoc_name) }
-
-          define_method("#{name}_amount")   { public_send(name)&.amount }
-          define_method("#{name}_format")   { public_send(name)&.amount&.format }
-          define_method("#{name}_in")       { |to| public_send(name)&.exchange_to(to)&.format }
-
-          # Sets the coin value with the specified amount and currency.
-          #
-          # @param amount [Money, Integer, Numeric] The amount to set
-          # @param currency_code [String, Symbol] The ISO currency code (e.g., 'USD', 'EUR')
-          # @return [Coin] The created or updated Coin object
-          # @raise [ArgumentError] If the amount type is not supported
-          #
-          # @example
-          #   product.set_price(amount: 29.99, currency_code: 'USD')
-          #   product.set_price(amount: Money.new(2999, 'USD'), currency_code: 'USD')
-          #   product.set_price(amount: 2999, currency_code: 'USD') # 2999 cents
-          define_method("set_#{name}") do |amount:, currency_code:|
-            iso = currency_code.to_s.upcase
-            coin = public_send(name) || public_send("build_#{assoc_name}", resource_label: label)
-            coin.currency_code  = iso
-            coin.currency_minor = to_cents(name, amount, iso)
-            coin.resource       = self
-            coin.save!
-
-            coin
-          end
-        end
-      end
+      has_one assoc_name,
+              -> { for_role(label) },
+              as: :resource,
+              class_name: 'WhittakerTech::Midas::Coin',
+              dependent: dependent
 
-      private
-
-      def to_cents(name, amount, iso)
-        raise ArgumentError, "Invalid value for #{name}: #{amount.inspect}" unless is_valid_type?(amount)
+      define_methods(name, label, assoc_name)
+    end
 
-        return amount.cents if amount.is_a? Money
-        return amount if amount.is_a? Integer
+    def define_methods(name, label, assoc_name)
+      define_method(name) { public_send(assoc_name) }
 
-        (BigDecimal(amount.to_s) * (10**decimals_for(iso))).round.to_i
-      end
+      define_method("#{name}_amount")   { public_send(name)&.amount }
+      define_method("#{name}_format")   { public_send(name)&.amount&.format }
+      # define_method("#{name}_in")       { |to| public_send(name)&.exchange_to(to)&.format }
 
-      def is_valid_type?(amount)
-        [Money, Integer, Numeric].any? { |klass| amount.is_a?(klass) }
-      end
-
-      # Determines the number of decimal places for a given currency.
+      # Sets the coin value with the specified amount and currency.
+      #
+      # @param amount [Money, Integer, Numeric] The amount to set
+      # @param currency_code [String, Symbol] The ISO currency code (e.g., 'USD', 'EUR')
+      # @return [Coin] The created or updated Coin object
+      # @raise [ArgumentError] If the amount type is not supported
       #
-      # @param iso [String] The ISO currency code
-      # @return [Integer] Number of decimal places (0-12)
-      def decimals_for(iso)
-        scope    = 'midas.ui'
-        per      = I18n.t("#{scope}.currencies.#{iso}", default: {})
-        default  = I18n.t("#{scope}.defaults.decimal_count", default: 2)
-        (per['decimal_count'] || default).to_i.clamp(0, 12)
+      # @example
+      #   product.set_price(amount: 29.99, currency_code: 'USD')
+      #   product.set_price(amount: Money.new(2999, 'USD'), currency_code: 'USD')
+      #   product.set_price(amount: 2999, currency_code: 'USD') # 2999 cents
+      define_method("set_#{name}") do |amount:, currency_code:|
+        iso = currency_code.to_s.upcase
+        coin = public_send(name) || public_send("build_#{assoc_name}", resource_role: label)
+        coin.currency_code  = iso
+        coin.currency_minor = to_cents(name, amount, iso)
+        coin.resource       = self
+        coin.save!
+
+        coin
       end
     end
   end
+
+  private
+
+  # Converts an amount in various representations to an integer minor-unit count.
+  #
+  # Input conversion rules:
+  #
+  # - `Money`: Uses `money.cents` directly (already minor units)
+  # - `Integer`: Assumed to already be minor units; returned as-is
+  # - `Numeric`: Treated as major units; scaled by `10 ** decimals_for`
+  #
+  # @param name [Symbol] attribute name used in error messages
+  # @param amount [Money, Integer, Numeric] the amount to convert
+  # @param iso [String] uppercased ISO 4217 currency code
+  # @return [Integer] minor-unit count (e.g. cents)
+  # @raise [ArgumentError] if `amount` is not a supported type
+  def to_cents(name, amount, iso)
+    raise ArgumentError, "Invalid value for #{name}: #{amount.inspect}" unless is_valid_type?(amount)
+
+    return amount.cents if amount.is_a? Money
+    return amount if amount.is_a? Integer
+
+    (BigDecimal(amount.to_s) * (10**decimals_for(iso))).round.to_i
+  end
+
+  # Returns true if `amount` is one of the accepted input types.
+  # @param amount [Object]
+  # @return [Boolean]
+  def is_valid_type?(amount)
+    [Money, Integer, Numeric].any? { |klass| amount.is_a?(klass) }
+  end
+
+  # Determines the number of decimal places for a given currency.
+  #
+  # Reads from `midas.ui.currencies.<ISO>.decimal_count` in I18n, falling
+  # back to `midas.ui.defaults.decimal_count` (default: `2`). Clamped to
+  # `[0, 12]` to prevent pathological scaling.
+  #
+  # @param iso [String] The ISO currency code
+  # @return [Integer] Number of decimal places (0-12)
+  def decimals_for(iso)
+    scope    = 'midas.ui'
+    per      = I18n.t("#{scope}.currencies.#{iso}", default: {})
+    default  = I18n.t("#{scope}.defaults.decimal_count", default: 2)
+    (per['decimal_count'] || default).to_i.clamp(0, 12)
+  end
 end

data/app/models/whittaker_tech/midas/application_record.rb

@@ -1,7 +1,3 @@
-module WhittakerTech
-  module Midas
-    class ApplicationRecord < ActiveRecord::Base
-      self.abstract_class = true
-    end
-  end
+class WhittakerTech::Midas::ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
 end