calc_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 89540dec57ad5480d42f475262ad432f1a275b7d0519287c3e5e2092977d4399
+  data.tar.gz: e3ef5386ea201bc2e1d6d7a1bd267d569f78785a8ed6920c3d63fb8963601175
+SHA512:
+  metadata.gz: 5ea9321a56fe0aa4b820ece61a754302a389831d66765c4dd4cbb6b1aa279f37d2d0a2b55553e67c15efbf1139539615be19aefd6a56bd45870a0daa3944b3ef
+  data.tar.gz: b99c06861ebb054cb65876689130a22f7a0818aa5eca7db59a89e6a955cc87ff7d49ebb589c23b84f5d3a2c0b412235894832ef3349d483f43ffe63629fd0a9b

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-06-01
+
+### Added
+
+- Declarative DSL for defining calculator inputs and outputs
+- Input types: string, integer, decimal, date, select, boolean
+- Output types: string, integer, decimal, date, currency, percentage
+- ActiveModel validations (required, min, max)
+- Calculator registry for lookup by slug
+- Rails engine with controller helpers and view helpers
+- Generators for install, calculator scaffolding
+- Optional persistence via Calculation model concern

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Tyler Schneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,221 @@
+# CalcKit
+
+A Ruby gem providing a declarative DSL for building calculators with automatic form generation, validation, and optional persistence. Works standalone with ActiveModel or as a Rails engine.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "calc_kit"
+```
+
+Then run the install generator:
+
+```bash
+rails g calc_kit:install
+```
+
+Options:
+- `--model` - Generate a Calculation model for persistence
+- `--views` - Copy default views to your app
+- `--scope=current_account` - Configure multi-tenancy scope
+
+## Usage
+
+### Defining a Calculator
+
+```ruby
+# app/calculators/price_calculator.rb
+class PriceCalculator < ApplicationCalculator
+  calculator_name "Price Calculator"
+  calculator_slug :price
+  version "1.0"
+
+  input :price, :decimal, label: "Unit Price", required: true, min: 0.01
+  input :quantity, :integer, label: "Quantity", required: true, min: 1
+  input :discount, :decimal, label: "Discount %", default: 0, min: 0, max: 100
+
+  output :subtotal, :decimal
+  output :total, :decimal
+
+  def calculate
+    sub = price * quantity
+    disc = sub * (discount / 100.0)
+    {
+      subtotal: sub,
+      total: sub - disc
+    }
+  end
+end
+
+CalcKit.register(PriceCalculator)
+```
+
+### Input Types
+
+- `:string` - Text input
+- `:integer` - Whole number input
+- `:decimal` - Decimal number input
+- `:date` - Date picker
+- `:select` - Dropdown (use `options:` to provide choices)
+- `:boolean` - Checkbox
+
+### Input Options
+
+```ruby
+input :name, :type,
+  label: "Display Label",      # Form label
+  required: true,              # Adds presence validation
+  min: 0,                      # Minimum value (numeric)
+  max: 100,                    # Maximum value (numeric)
+  step: 0.01,                  # Step increment (decimal)
+  default: 10,                 # Default value (can be a proc)
+  placeholder: "Enter value",  # Placeholder text
+  hint: "Help text",           # Help text below input
+  options: [["Label", "value"], ...] # For :select type
+```
+
+### Output Types
+
+- `:string` - Plain text
+- `:integer` - Formatted integer
+- `:decimal` - Formatted decimal (2 places)
+- `:date` - Formatted date
+- `:currency` - Currency formatted
+- `:percentage` - Percentage formatted
+
+### Running Calculations
+
+```ruby
+calc = PriceCalculator.new(price: 10, quantity: 5, discount: 10)
+
+if calc.valid?
+  result = calc.run
+  # => { subtotal: 50.0, total: 45.0 }
+end
+
+# Or use run! to raise on validation errors
+result = calc.run!
+```
+
+### Controller Integration
+
+```ruby
+class CalculatorsController < ApplicationController
+  include CalcKit::ControllerHelpers
+
+  def show
+    @calculator_class = find_calculator_class(params[:slug])
+    @calculator = build_calculator(@calculator_class)
+    @saved_calculations = load_saved_calculations(@calculator_class)
+  end
+
+  def create
+    @calculator_class = find_calculator_class(params[:slug])
+    @calculator = build_calculator(@calculator_class)
+    @result = @calculator.run
+
+    if @result
+      save_calculation(@calculator, @result) if params[:save].present?
+      # ...
+    end
+  end
+end
+```
+
+### View Helpers
+
+```erb
+<%# Resolve callable defaults %>
+<%= calc_kit_resolve_default(input.default) %>
+
+<%# Format output values %>
+<%= calc_kit_format_output(result[:total], :currency) %>
+
+<%# CSS classes %>
+<%= calc_kit_input_class(calculator, input) %>
+<%= calc_kit_label_class %>
+<%= calc_kit_error_class %>
+```
+
+## Configuration
+
+```ruby
+# config/initializers/calc_kit.rb
+CalcKit.configure do |config|
+  # Path to calculator classes
+  config.calculators_path = "app/calculators"
+
+  # Auto-register calculators on load
+  config.auto_register = true
+
+  # Multi-tenancy scope method
+  config.scope_method = :current_account
+
+  # Enable Turbo Streams
+  config.enable_turbo_streams = true
+
+  # Enable calculation persistence
+  config.save_calculations = true
+
+  # Default CSS classes
+  config.default_form_classes = {
+    input: "form-control",
+    label: "block text-sm font-medium mb-1",
+    error: "text-red-500 text-sm mt-1",
+    submit: "btn btn-primary"
+  }
+end
+```
+
+## Generators
+
+```bash
+# Install calc_kit
+rails g calc_kit:install
+
+# Generate a new calculator
+rails g calc_kit:calculator shipping
+```
+
+## Roadmap
+
+Potential future enhancements:
+
+### Input Enhancements
+- [ ] Input groups for organizing related fields
+- [ ] Conditional inputs (show/hide based on other values)
+- [ ] Custom validators beyond min/max
+- [ ] More types: `:textarea`, `:radio`, `:checkbox_group`, `:range`
+
+### Output Enhancements
+- [ ] Custom formatters
+- [ ] Conditional outputs (only show if value present)
+- [ ] Output groups/sections
+
+### Calculator Features
+- [ ] Calculator descriptions for index pages
+- [ ] Categories/tags for organizing calculators
+- [ ] Comparison mode (side-by-side with different inputs)
+- [ ] Calculator dependencies (one calculator feeds into another)
+
+### Export & Sharing
+- [ ] PDF export of results
+- [ ] CSV export for saved calculations
+- [ ] Shareable result links
+- [ ] Embeddable calculator widgets
+
+### Developer Experience
+- [ ] Controller scaffold generator
+- [ ] API endpoint generator
+- [ ] JavaScript client for real-time calculation preview
+- [ ] Form builder integration (SimpleForm, Formtastic)
+
+### Testing
+- [ ] Calculator test helpers
+- [ ] Shared examples for common patterns
+
+## License
+
+MIT License

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/calc_kit.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/calc_kit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "calc_kit"
+  spec.version = CalcKit::VERSION
+  spec.authors = ["Tyler Schneider"]
+  spec.email = ["tylercschneider@gmail.com"]
+
+  spec.summary = "A DSL for building calculators with automatic form generation"
+  spec.description = "CalcKit provides a declarative DSL for defining calculators with inputs, outputs, validation, and optional persistence. Works standalone or as a Rails engine."
+  spec.homepage = "https://github.com/tylercschneider/calc_kit"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor docs/ Gemfile CLAUDE.md])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activemodel", ">= 7.0"
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "railties", ">= 7.0"
+end

data/lib/calc_kit/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module CalcKit
+  # Base class for all calculators with a declarative DSL
+  #
+  # Responsibilities (Single Responsibility):
+  # - Defines DSL for declaring calculator metadata, inputs, and outputs
+  # - Provides validation through ActiveModel
+  #
+  # Open/Closed: New calculators extend this class without modifying it
+  # Liskov Substitution: All subclasses can be used interchangeably via #run
+  # Interface Segregation: InputDefinition and OutputDefinition are separate classes
+  # Dependency Inversion: Uses ActiveModel abstractions, not concrete implementations
+  #
+  class Base
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include DSL
+
+    # Run calculation if valid, return nil if invalid
+    def run
+      return nil unless valid?
+      calculate
+    end
+
+    # Run calculation, raise if invalid
+    def run!
+      raise ActiveModel::ValidationError, self unless valid?
+      calculate
+    end
+
+    # Subclasses must implement this
+    def calculate
+      raise NotImplementedError, "#{self.class.name} must implement #calculate"
+    end
+
+    # Returns input values as a hash
+    def input_values
+      self.class.inputs.each_with_object({}) do |input, hash|
+        hash[input.name] = send(input.name)
+      end
+    end
+
+    # Returns the calculator name
+    def calculator_name
+      self.class.calculator_name
+    end
+
+    # Returns the calculator slug
+    def calculator_slug
+      self.class.calculator_slug
+    end
+
+    # Returns the calculator version
+    def version
+      self.class.version
+    end
+  end
+end

data/lib/calc_kit/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CalcKit
+  class Configuration
+    attr_accessor :calculators_path,
+                  :auto_register,
+                  :scope_method,
+                  :enable_turbo_streams,
+                  :save_calculations,
+                  :warn_on_version_mismatch
+
+    def initialize
+      @calculators_path = "app/calculators"
+      @auto_register = true
+      @scope_method = nil
+      @enable_turbo_streams = true
+      @save_calculations = true
+      @warn_on_version_mismatch = true
+    end
+  end
+end

data/lib/calc_kit/dsl.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # DSL module providing class-level macros for calculator definitions
+  module DSL
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        class_attribute :_calculator_name, :_calculator_slug, :_calculator_version,
+                        :_inputs, :_outputs, instance_writer: false
+
+        self._inputs = []
+        self._outputs = []
+      end
+    end
+
+    module ClassMethods
+      def calculator_name(name = nil)
+        if name
+          self._calculator_name = name
+        else
+          _calculator_name
+        end
+      end
+
+      def calculator_slug(slug = nil)
+        if slug
+          self._calculator_slug = slug.to_sym
+        else
+          _calculator_slug
+        end
+      end
+
+      def version(v = nil)
+        if v
+          self._calculator_version = v
+        else
+          _calculator_version
+        end
+      end
+
+      def input(name, type, **options)
+        self._inputs = _inputs + [InputDefinition.new(name, type, options)]
+
+        # Define attribute using ActiveModel::Attributes
+        attribute name, type_for_attribute(type)
+
+        # Add validations based on options
+        validates name, presence: true if options[:required]
+
+        if options[:min]
+          validates name, numericality: { greater_than_or_equal_to: options[:min] }, allow_blank: true
+        end
+
+        if options[:max]
+          validates name, numericality: { less_than_or_equal_to: options[:max] }, allow_blank: true
+        end
+      end
+
+      def output(name, type, **options)
+        self._outputs = _outputs + [OutputDefinition.new(name, type, options)]
+      end
+
+      def inputs
+        _inputs
+      end
+
+      def outputs
+        _outputs
+      end
+
+      def input_for(name)
+        _inputs.find { |i| i.name == name }
+      end
+
+      def output_for(name)
+        _outputs.find { |o| o.name == name }
+      end
+
+      private
+
+      VALID_INPUT_TYPES = %i[string integer decimal date boolean select].freeze
+
+      def type_for_attribute(type)
+        unless VALID_INPUT_TYPES.include?(type)
+          raise ArgumentError, "Unknown input type: #{type.inspect}. Valid types: #{VALID_INPUT_TYPES.join(", ")}"
+        end
+
+        case type
+        when :date then :date
+        when :integer then :integer
+        when :decimal then :decimal
+        when :boolean then :boolean
+        when :string, :select then :string
+        end
+      end
+    end
+  end
+end

data/lib/calc_kit/engine.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module CalcKit
+  class Engine < ::Rails::Engine
+    isolate_namespace CalcKit
+
+    config.autoload_paths << root.join("lib")
+
+    initializer "calc_kit.eager_load_calculators" do |app|
+      app.config.to_prepare do
+        if CalcKit.configuration.auto_register
+          calculators_path = ::Rails.root.join(CalcKit.configuration.calculators_path)
+          if calculators_path.exist?
+            ::Rails.autoloaders.main.eager_load_dir(calculators_path)
+          end
+        end
+      end
+    end
+
+    initializer "calc_kit.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include CalcKit::ViewHelpers
+      end
+    end
+
+    initializer "calc_kit.controller_helpers" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include CalcKit::ControllerHelpers
+      end
+    end
+  end
+end
+
+require_relative "rails/controller_helpers"
+require_relative "rails/view_helpers"
+require_relative "rails/model"

data/lib/calc_kit/input_definition.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # Value object for input field definitions
+  class InputDefinition
+    attr_reader :name, :type, :options
+
+    def initialize(name, type, options = {})
+      @name = name
+      @type = type
+      @options = options
+    end
+
+    def label
+      options[:label] || name.to_s.tr("_", " ").capitalize
+    end
+
+    def required?
+      options[:required] == true
+    end
+
+    def default
+      options[:default]
+    end
+
+    def placeholder
+      options[:placeholder]
+    end
+
+    def min
+      options[:min]
+    end
+
+    def max
+      options[:max]
+    end
+
+    def step
+      options[:step]
+    end
+
+    def options_for_select
+      options[:options]
+    end
+
+    def hint
+      options[:hint]
+    end
+
+    def ==(other)
+      other.is_a?(InputDefinition) &&
+        name == other.name &&
+        type == other.type &&
+        options == other.options
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [name, type, options].hash
+    end
+  end
+end

data/lib/calc_kit/output_definition.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # Value object for output field definitions
+  class OutputDefinition
+    attr_reader :name, :type, :options
+
+    def initialize(name, type, options = {})
+      @name = name
+      @type = type
+      @options = options
+    end
+
+    def label
+      options[:label] || name.to_s.tr("_", " ").capitalize
+    end
+
+    def format
+      options[:format]
+    end
+
+    def ==(other)
+      other.is_a?(OutputDefinition) &&
+        name == other.name &&
+        type == other.type &&
+        options == other.options
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      [name, type, options].hash
+    end
+  end
+end