whittaker_tech-midas 0.1.0

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

@@ -0,0 +1,184 @@
+# 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
+    #
+    # == 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 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
+
+      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
+            cents =
+              case amount
+              when Money then amount.cents
+              when Integer then amount
+              when Numeric then (BigDecimal(amount.to_s) * (10**decimals_for(iso))).round.to_i
+              else raise ArgumentError, "Invalid value for #{name}: #{amount.inspect}"
+              end
+
+            coin = public_send(name) || public_send("build_#{assoc_name}", resource_label: label)
+            coin.currency_code  = iso
+            coin.currency_minor = cents
+            coin.resource       = self
+            coin.save!
+
+            coin
+          end
+        end
+      end
+
+      private
+
+      # Determines the number of decimal places for a given currency.
+      #
+      # @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
+  end
+end

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

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

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module WhittakerTech
+  module Midas
+    class Coin < ApplicationRecord
+      self.table_name = 'wt_midas_coins'
+
+      belongs_to :resource, polymorphic: true
+
+      before_validation :normalize_fields
+
+      validates :resource_label,
+                presence: true,
+                format: { with: /\A[a-z0-9_]+\z/ },
+                length: { maximum: 64 },
+                uniqueness: { scope: %i[resource_type resource_id], case_sensitive: false }
+
+      validates :currency_code,  presence: true, length: { is: 3 }
+      validates :currency_minor, presence: true, numericality: { only_integer: true }
+
+      # Returns a Money object representing the stored monetary value.
+      # Memoized for performance in hot paths.
+      def amount
+        @amount ||= Money.new(currency_minor, currency_code)
+      end
+
+      # Sets the coin's monetary value from various input types.
+      def amount=(value)
+        case value
+        when Money
+          self.currency_minor = value.cents
+          self.currency_code = value.currency.iso_code
+        when Numeric
+          raise ArgumentError, 'currency_code required before setting numeric amount' if currency_code.blank?
+
+          self.currency_minor = Integer(value)
+        else
+          raise ArgumentError, "Invalid value for Coin#amount: #{value.inspect}"
+        end
+      end
+
+      delegate :exchange_to, to: :amount
+
+      def format(to: nil)
+        (to ? exchange_to(to) : amount).format
+      end
+
+      # Convenient aliases for form helpers
+      def minor
+        currency_minor
+      end
+
+      def currency
+        currency_code
+      end
+
+      def fractional
+        currency_minor
+      end
+
+      # Override setters to clear memoization
+      def currency_minor=(value)
+        @amount = nil
+        super
+      end
+
+      def currency_code=(value)
+        @amount = nil
+        super
+      end
+
+      private
+
+      # Normalize inputs for consistency and case-insensitive uniqueness
+      def normalize_fields
+        self.resource_label = resource_label.to_s.strip.downcase.presence if resource_label
+        self.currency_code = currency_code.to_s.strip.upcase.presence if currency_code
+      end
+    end
+  end
+end

data/app/views/layouts/whittaker_tech/midas/application.html.erb

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Whittaker tech midas</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= stylesheet_link_tag    "whittaker_tech/midas/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/app/views/layouts/whittaker_tech/midas/shared/_currency_field.html.erb

@@ -0,0 +1,49 @@
+<%
+  # Headless currency input field for Money-like objects.
+  #
+  # Locals:
+  #   form: FormBuilder
+  #   attribute: Symbol, e.g. :price
+  #   value: Money object (responds to #fractional and #currency.iso_code)
+  #   decimals: Integer (default: 2)
+  #   input_html: Hash (optional)
+  #   wrapper_html: Hash (optional)
+  #   label_text: String (optional, defaults to humanized attribute)
+  #   show_label: Boolean (default: false)
+  #
+  input_id      = "#{form.object_name}_#{attribute}_display"
+  money_value   = value || Money.new(0, "USD")
+  current_minor = money_value.fractional
+  currency_code = money_value.currency.iso_code
+  decimals      ||= 2
+  input_html    ||= {}
+  wrapper_html  ||= {}
+  show_label    ||= false
+  label_text    = label_text.presence || attribute.to_s.humanize
+%>
+
+<div <%= tag.attributes(wrapper_html) %>
+     data-controller="midas-currency"
+     data-midas-currency-currency-value="<%= currency_code %>"
+     data-midas-currency-decimals-value="<%= decimals %>">
+
+  <%= form.label "#{attribute}_display",
+                 label_text,
+                 for: input_id,
+                 class: (show_label ? nil : "sr-only") %>
+
+  <input type="text"
+         id="<%= input_id %>"
+         name="<%= form.object_name %>[<%= attribute %>_display]"
+         data-midas-currency-target="display"
+         data-action="beforeinput->midas-currency#input keydown->midas-currency#backspace keydown->midas-currency#preventDefault"
+         inputmode="decimal"
+         autocomplete="off"
+         <%= tag.attributes(input_html) %>>
+
+  <%= form.hidden_field "#{attribute}_minor",
+                        value: current_minor,
+                        data: { midas_currency_target: "hidden" } %>
+
+  <%= form.hidden_field "#{attribute}_currency", value: currency_code %>
+</div>

data/config/locales/midas.en.yml

@@ -0,0 +1,58 @@
+# WhittakerTech::Midas I18n Configuration
+#
+# This file defines currency-specific settings used by the Bankable concern
+# for decimal precision when converting numeric values to minor units.
+#
+# Add more currencies as needed following the ISO 4217 standard.
+
+en:
+  midas:
+    ui:
+      defaults:
+        decimal_count: 2
+      currencies:
+        # Major currencies
+        USD:
+          decimal_count: 2
+          symbol: "$"
+          symbol_position: left
+        EUR:
+          decimal_count: 2
+          symbol: "€"
+          symbol_position: left
+        GBP:
+          decimal_count: 2
+          symbol: "£"
+          symbol_position: left
+        JPY:
+          decimal_count: 0
+          symbol: "¥"
+          symbol_position: left
+        CNY:
+          decimal_count: 2
+          symbol: "¥"
+          symbol_position: left
+        
+        # Additional currencies
+        CAD:
+          decimal_count: 2
+          symbol: "$"
+          symbol_position: left
+        AUD:
+          decimal_count: 2
+          symbol: "$"
+          symbol_position: left
+        CHF:
+          decimal_count: 2
+          symbol: "Fr"
+          symbol_position: left
+        INR:
+          decimal_count: 2
+          symbol: "₹"
+          symbol_position: left
+        
+        # Cryptocurrency (if needed)
+        BTC:
+          decimal_count: 8
+          symbol: "₿"
+          symbol_position: left

data/config/routes.rb

@@ -0,0 +1,2 @@
+WhittakerTech::Midas::Engine.routes.draw do
+end

data/db/migrate/20251015160523_create_wt_midas_coins.rb

@@ -0,0 +1,16 @@
+class CreateWtMidasCoins < ActiveRecord::Migration[8.0]
+  def change
+    create_table :wt_midas_coins do |t|
+      t.references :resource, polymorphic: true, null: false, index: true
+      t.string :resource_label, null: false, limit: 64
+      t.string :currency_code, null: false, limit: 3
+      t.bigint :currency_minor, null: false
+
+      t.timestamps
+
+      t.index %i[resource_id resource_type resource_label],
+              unique: true,
+              name: 'index_wt_midas_coins_on_owner_and_label'
+    end
+  end
+end

data/lib/tasks/whittaker_tech/midas_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :whittaker_tech_midas do
+#   # Task goes here
+# end

data/lib/whittaker_tech/midas/engine.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module WhittakerTech
+  module Midas
+    # The Midas Engine provides monetary value management capabilities as a Rails Engine.
+    # It integrates seamlessly with Rails applications to add currency handling, coin management,
+    # and monetary formatting functionality through the Bankable concern and related components.
+    #
+    # This engine follows Rails Engine conventions and can be mounted in any Rails application
+    # to provide comprehensive monetary value handling capabilities. It includes models, helpers,
+    # and utilities for working with currencies and monetary amounts.
+    #
+    # == Features
+    #
+    # - **Bankable Concern**: Allows any Active Record model to have monetary attributes
+    # - **Coin Model**: Stores monetary values with currency information
+    # - **Form Helpers**: View helpers for monetary input and display
+    # - **Currency Management**: Integration with the Money gem for currency operations
+    # - **Namespace Isolation**: Clean separation from host application code
+    #
+    # == Installation and Setup
+    #
+    # Add the engine to your Rails application's Gemfile and run bundle install.
+    # The engine will automatically configure itself when Rails boots.
+    #
+    # @example Adding to a Rails application
+    #   # In your Gemfile
+    #   gem 'whittaker_tech-midas'
+    #
+    #   # The engine auto-configures on Rails boot
+    #   # No additional setup required
+    #
+    # == Usage in Host Applications
+    #
+    # Once installed, the engine's functionality becomes available throughout
+    # your Rails application:
+    #
+    # @example Using Bankable in models
+    #   class Product < ApplicationRecord
+    #     include WhittakerTech::Midas::Bankable
+    #     has_coin :price
+    #   end
+    #
+    # @example Using form helpers in views
+    #   <%= form_with model: @product do |form| %>
+    #     <%= form.money_field :price %>
+    #   <% end %>
+    #
+    # == Configuration
+    #
+    # The engine provides several configuration points:
+    #
+    # - **Eager Loading**: Automatically configures model loading paths
+    # - **Helper Integration**: Injects form helpers into ActionView
+    # - **Namespace Isolation**: Keeps engine code separate from host application
+    #
+    # == Directory Structure
+    #
+    # The engine follows standard Rails Engine structure:
+    # - `app/models/`: Coin model and concerns
+    # - `app/helpers/`: Form helpers for monetary inputs
+    # - `db/migrate/`: Database migrations for coin storage
+    # - `lib/`: Engine configuration and initialization
+    #
+    # == Database Integration
+    #
+    # The engine provides database migrations that create the necessary tables
+    # for storing monetary values. Run migrations after installation:
+    #
+    # @example Running migrations
+    #   rails db:migrate
+    #
+    # == Namespace Isolation
+    #
+    # The engine uses `isolate_namespace` to prevent conflicts with host
+    # application code. All engine components are properly namespaced under
+    # `WhittakerTech::Midas`.
+    #
+    # == Helper Integration
+    #
+    # Form helpers are automatically made available in all views through
+    # an initializer that extends ActionView::Base when the view layer loads.
+    # This provides seamless integration without requiring manual includes.
+    #
+    # == Eager Loading
+    #
+    # The engine configures additional eager load paths to ensure all models
+    # are properly loaded in production environments. This includes the models
+    # directory which contains the Coin model and Bankable concern.
+    #
+    # == Thread Safety
+    #
+    # The engine follows Rails conventions for thread safety and can be safely
+    # used in multi-threaded environments like Puma or Falcon.
+    #
+    # == Development and Testing
+    #
+    # The engine can be developed and tested independently using its own
+    # test suite, or integrated into a host application for testing.
+    #
+    # @see WhittakerTech::Midas::Bankable
+    # @see WhittakerTech::Midas::Coin
+    # @see WhittakerTech::Midas::FormHelper
+    # @since 0.1.0
+    class Engine < ::Rails::Engine
+      isolate_namespace WhittakerTech::Midas
+
+      config.eager_load_paths += Dir["#{config.root}/app/models"]
+
+      initializer 'midas.helpers' do
+        ActiveSupport.on_load(:action_view) do
+          include WhittakerTech::Midas::FormHelper
+        end
+      end
+    end
+  end
+end

data/lib/whittaker_tech/midas/version.rb

@@ -0,0 +1,5 @@
+module WhittakerTech
+  module Midas
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/whittaker_tech/midas.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'whittaker_tech/midas/version'
+require 'whittaker_tech/midas/engine'
+require 'money'
+
+module WhittakerTech
+  module Midas
+    # Your code goes here...
+  end
+end