calc_kit 0.1.0

data/lib/calc_kit/rails/controller_helpers.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # Controller helpers for calculator actions
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :calc_kit_scope if respond_to?(:helper_method)
+    end
+
+    private
+
+    # Find a calculator class by slug, raises if not found
+    def find_calculator_class(slug)
+      CalcKit.find(slug) || raise(CalcKit::NotFoundError, "Calculator not found: #{slug}")
+    end
+
+    # Build a calculator instance from params
+    def build_calculator(calculator_class, params_hash = nil)
+      params_hash ||= calculator_params_for(calculator_class)
+      calculator_class.new(params_hash)
+    end
+
+    # Extract permitted params for a calculator
+    def calculator_params_for(calculator_class)
+      permitted = calculator_class.inputs.map(&:name)
+      params.permit(*permitted).to_h.reject { |_, v| v.blank? }
+    end
+
+    # Save a calculation result
+    def save_calculation(calculator, result, calculation_class: nil)
+      return unless CalcKit.configuration.save_calculations
+
+      calculation_class ||= "Calculation".safe_constantize
+      return unless calculation_class
+
+      scope = calc_kit_scope
+      attrs = {
+        calculator_type: calculator.class.calculator_slug.to_s,
+        calculator_version: calculator.class.version,
+        inputs: calculator.input_values,
+        outputs: result
+      }
+
+      if scope
+        scope.calculations.create!(attrs)
+      else
+        calculation_class.create!(attrs)
+      end
+    end
+
+    # Load saved calculations for a calculator
+    def load_saved_calculations(calculator_class, limit: 5, calculation_class: nil)
+      return [] unless CalcKit.configuration.save_calculations
+
+      calculation_class ||= "Calculation".safe_constantize
+      return [] unless calculation_class
+
+      scope = calc_kit_scope
+      relation = scope ? scope.calculations : calculation_class
+      relation
+        .where(calculator_type: calculator_class.calculator_slug.to_s)
+        .order(created_at: :desc)
+        .limit(limit)
+    end
+
+    # Returns the scope for multi-tenancy (e.g., current_account)
+    def calc_kit_scope
+      scope_method = CalcKit.configuration.scope_method
+      return nil unless scope_method
+
+      respond_to?(scope_method, true) ? send(scope_method) : nil
+    end
+  end
+end

data/lib/calc_kit/rails/model.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # Concern for the Calculation model that stores calculation results
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      validates :calculator_type, presence: true
+      validates :calculator_version, presence: true
+      validates :inputs, presence: true
+      validates :outputs, presence: true
+    end
+
+    # Returns the calculator class for this calculation
+    def calculator_class
+      CalcKit.find(calculator_type)
+    end
+
+    # Returns a new calculator instance populated with the saved inputs
+    def to_calculator
+      klass = calculator_class
+      return nil unless klass
+
+      klass.new(inputs.symbolize_keys)
+    end
+
+    # Check if the calculator version matches the current version
+    def version_current?
+      klass = calculator_class
+      return false unless klass
+
+      klass.version == calculator_version
+    end
+
+    # Check if there's a version mismatch
+    def version_mismatch?
+      !version_current?
+    end
+
+    module ClassMethods
+      # Scope to filter by calculator type
+      def for_calculator(slug)
+        where(calculator_type: slug.to_s)
+      end
+    end
+  end
+end

data/lib/calc_kit/rails/view_helpers.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # View helpers for rendering calculator forms and results
+  module ViewHelpers
+    # Resolve a default value, calling it if it's a proc
+    def calc_kit_resolve_default(default)
+      default.respond_to?(:call) ? default.call : default
+    end
+
+    # Format an output value based on its type
+    def calc_kit_format_output(value, type)
+      return "" if value.nil?
+
+      case type
+      when :date
+        value&.respond_to?(:to_fs) ? value.to_fs(:long) : value.to_s
+      when :decimal
+        if respond_to?(:number_with_precision)
+          number_with_precision(value, precision: 2)
+        else
+          format("%.2f", value.to_f)
+        end
+      when :integer
+        value.to_i.to_s
+      when :currency
+        if respond_to?(:number_to_currency)
+          number_to_currency(value)
+        else
+          format("$%.2f", value.to_f)
+        end
+      when :percentage
+        if respond_to?(:number_to_percentage)
+          number_to_percentage(value, precision: 1)
+        else
+          format("%.1f%%", value.to_f)
+        end
+      else
+        value.to_s
+      end
+    end
+
+    KEYSTONE_TYPE_MAP = {
+      string: :text,
+      integer: :number,
+      decimal: :number,
+      date: :date,
+      select: :select,
+      boolean: :checkbox
+    }.freeze
+
+    # Map CalcKit input type to keystone_ui form field type
+    def calc_kit_keystone_type(type)
+      KEYSTONE_TYPE_MAP.fetch(type, :text)
+    end
+
+    # Returns a warning string if the calculation was made with a different
+    # calculator version, or nil if versions match or warnings are disabled.
+    def calc_kit_version_warning(calculation)
+      return nil unless CalcKit.configuration.warn_on_version_mismatch
+      return nil unless calculation.version_mismatch?
+
+      "This calculation was made with a different version of the calculator and may have outdated results."
+    end
+  end
+end

data/lib/calc_kit/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module CalcKit
+  # Registry for calculator lookup by slug
+  class Registry
+    def initialize
+      @calculators = {}
+    end
+
+    def register(calculator_class)
+      slug = calculator_class.calculator_slug
+      raise ArgumentError, "Calculator must define a slug" unless slug
+
+      @calculators[slug.to_sym] = calculator_class
+    end
+
+    def find(slug)
+      @calculators[slug.to_sym]
+    end
+
+    def all
+      @calculators.values
+    end
+
+    def slugs
+      @calculators.keys
+    end
+
+    def clear
+      @calculators.clear
+    end
+
+    def registered?(slug)
+      @calculators.key?(slug.to_sym)
+    end
+  end
+end

data/lib/calc_kit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CalcKit
+  VERSION = "0.1.0"
+end

data/lib/calc_kit.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "calc_kit/version"
+require_relative "calc_kit/configuration"
+require_relative "calc_kit/input_definition"
+require_relative "calc_kit/output_definition"
+require_relative "calc_kit/dsl"
+require_relative "calc_kit/registry"
+require_relative "calc_kit/base"
+
+module CalcKit
+  class NotFoundError < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def register(calculator_class)
+      registry.register(calculator_class)
+    end
+
+    def find(slug)
+      registry.find(slug)
+    end
+
+    def all
+      registry.all
+    end
+  end
+end
+
+# Load Rails engine if Rails is present
+require_relative "calc_kit/engine" if defined?(Rails::Engine)

data/lib/generators/calc_kit/calculator_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module CalcKit
+  module Generators
+    class CalculatorGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_test, type: :boolean, default: false,
+        desc: "Skip generating test file"
+
+      def create_calculator
+        template "calculator.rb.tt", "app/calculators/#{file_name}_calculator.rb"
+      end
+
+      def create_test
+        return if options[:skip_test]
+
+        template "calculator_test.rb.tt", "test/calculators/#{file_name}_calculator_test.rb"
+      end
+
+      private
+
+      def class_name
+        file_name.camelize
+      end
+
+      def calculator_name
+        file_name.titleize
+      end
+
+      def calculator_slug
+        file_name.underscore
+      end
+    end
+  end
+end

data/lib/generators/calc_kit/install_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/base"
+
+module CalcKit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :model, type: :boolean, default: false,
+        desc: "Generate Calculation model and migration"
+      class_option :views, type: :boolean, default: false,
+        desc: "Copy default views to app/views/calculators"
+      class_option :scope, type: :string, default: nil,
+        desc: "Multi-tenancy scope method (e.g., current_account)"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/calc_kit.rb"
+      end
+
+      def create_calculators_directory
+        empty_directory "app/calculators"
+      end
+
+      def create_application_calculator
+        template "application_calculator.rb.tt", "app/calculators/application_calculator.rb"
+      end
+
+      def create_model
+        return unless options[:model]
+
+        template "calculation.rb.tt", "app/models/calculation.rb"
+        migration_template "create_calculations.rb.tt",
+          "db/migrate/create_calculations.rb",
+          migration_version: migration_version
+      end
+
+      def copy_views
+        return unless options[:views]
+
+        directory "views", "app/views/calculators"
+      end
+
+      def show_post_install_message
+        say ""
+        say "CalcKit installed successfully!", :green
+        say ""
+        say "Next steps:"
+        say "  1. Run `rails db:migrate` if you generated the model"
+        say "  2. Create a calculator: `rails g calc_kit:calculator my_calculator`"
+        say "  3. Define inputs, outputs, and the calculate method"
+        say "  4. Register your calculator at the bottom of the file"
+        say ""
+      end
+
+      private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+      end
+
+      def scope_method
+        options[:scope]
+      end
+    end
+  end
+end

data/lib/generators/calc_kit/templates/application_calculator.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Base class for all calculators in this application.
+# Inherits from CalcKit::Base which provides the DSL.
+#
+# Add shared behavior, validations, or methods here.
+#
+class ApplicationCalculator < CalcKit::Base
+  # Example shared method:
+  # def formatted_currency(amount)
+  #   "$%.2f" % amount
+  # end
+end

data/lib/generators/calc_kit/templates/calculation.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+class Calculation < ApplicationRecord
+  include CalcKit::Model
+<% if scope_method -%>
+
+  belongs_to :<%= scope_method.to_s.sub("current_", "") %>, optional: true
+<% end -%>
+end

data/lib/generators/calc_kit/templates/calculator.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class <%= class_name %>Calculator < ApplicationCalculator
+  calculator_name "<%= calculator_name %>"
+  calculator_slug :<%= calculator_slug %>
+  version "1.0"
+
+  # Define inputs
+  # input :price, :decimal, label: "Price", required: true, min: 0.01
+  # input :quantity, :integer, label: "Quantity", required: true, min: 1
+
+  # Define outputs
+  # output :total, :decimal
+  # output :summary, :string
+
+  def calculate
+    # Return a hash with output values
+    # {
+    #   total: price * quantity,
+    #   summary: "#{quantity} items at $#{price} each"
+    # }
+    raise NotImplementedError, "Implement the calculate method"
+  end
+end
+
+# Register the calculator
+CalcKit.register(<%= class_name %>Calculator)

data/lib/generators/calc_kit/templates/calculator_test.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class <%= class_name %>CalculatorTest < ActiveSupport::TestCase
+  def setup
+    @calculator = <%= class_name %>Calculator.new
+  end
+
+  test "calculator is registered" do
+    assert_equal <%= class_name %>Calculator, CalcKit.find(:<%= calculator_slug %>)
+  end
+
+  test "calculator has required metadata" do
+    assert_equal "<%= calculator_name %>", <%= class_name %>Calculator.calculator_name
+    assert_equal :<%= calculator_slug %>, <%= class_name %>Calculator.calculator_slug
+    assert_equal "1.0", <%= class_name %>Calculator.version
+  end
+
+  # test "validates required inputs" do
+  #   assert_not @calculator.valid?
+  #   assert_includes @calculator.errors[:price], "can't be blank"
+  # end
+
+  # test "calculates correctly with valid inputs" do
+  #   calculator = <%= class_name %>Calculator.new(price: 10.0, quantity: 5)
+  #   result = calculator.run
+  #
+  #   assert_not_nil result
+  #   assert_equal 50.0, result[:total]
+  # end
+end

data/lib/generators/calc_kit/templates/create_calculations.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateCalculations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :calculations do |t|
+<% if scope_method -%>
+      t.references :<%= scope_method.to_s.sub("current_", "") %>, null: true, foreign_key: true
+<% end -%>
+      t.string :calculator_type, null: false
+      t.string :calculator_version, null: false
+      t.jsonb :inputs, null: false, default: {}
+      t.jsonb :outputs, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :calculations, :calculator_type
+<% if scope_method -%>
+    add_index :calculations, [:<%= scope_method.to_s.sub("current_", "") %>_id, :calculator_type]
+<% end -%>
+  end
+end

data/lib/generators/calc_kit/templates/initializer.rb.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+CalcKit.configure do |config|
+  # Path to calculator classes (relative to Rails.root)
+  # config.calculators_path = "app/calculators"
+
+  # Automatically register calculators on load
+  # config.auto_register = true
+<% if scope_method -%>
+
+  # Multi-tenancy scope method
+  config.scope_method = :<%= scope_method %>
+<% else -%>
+
+  # Multi-tenancy scope method (e.g., :current_account, :current_user)
+  # config.scope_method = nil
+<% end -%>
+
+  # Enable Turbo Streams for form responses
+  # config.enable_turbo_streams = true
+
+  # Enable saving calculations to the database
+  # config.save_calculations = true
+
+  # Warn when loading a calculation with a different version
+  # config.warn_on_version_mismatch = true
+end

data/lib/generators/calc_kit/templates/views/_form.html.erb

@@ -0,0 +1,30 @@
+<%%= ui_form action: calculator_path(slug: calculator.class.calculator_slug),
+             method: :post,
+             data: { turbo_stream: true } do %>
+
+  <%% calculator.class.inputs.each do |input| %>
+    <%%= ui_form_field attribute: input.name,
+          label: input.label,
+          type: calc_kit_keystone_type(input.type),
+          required: input.required?,
+          hint: input.hint,
+          placeholder: input.placeholder,
+          min: input.min,
+          max: input.max,
+          step: input.type == :decimal ? (input.step || "0.01") : (input.type == :integer ? 1 : nil),
+          value: calculator.send(input.name) || calc_kit_resolve_default(input.default),
+          options: input.respond_to?(:options_for_select) ? input.options_for_select : [],
+          errors: calculator.errors[input.name].to_a %>
+  <%% end %>
+
+  <div class="flex items-center gap-4">
+    <%%= ui_button label: "Calculate", type: :submit %>
+
+    <%% if defined?(user_signed_in?) && user_signed_in? %>
+      <label class="inline-flex items-center">
+        <%%= check_box_tag :save, "1", false, class: "form-checkbox rounded" %>
+        <span class="ml-2 text-sm">Save to my calculations</span>
+      </label>
+    <%% end %>
+  </div>
+<%% end %>

data/lib/generators/calc_kit/templates/views/_result.html.erb

@@ -0,0 +1,17 @@
+<div id="calculator_result">
+  <%% if result %>
+    <div class="mt-6">
+      <%%= ui_panel do %>
+        <h3 class="text-lg font-semibold mb-4">Result</h3>
+        <dl class="space-y-2">
+          <%% calculator.class.outputs.each do |output| %>
+            <div class="flex justify-between">
+              <dt class="font-medium"><%%= output.label %>:</dt>
+              <dd><%%= calc_kit_format_output(result[output.name], output.type) %></dd>
+            </div>
+          <%% end %>
+        </dl>
+      <%% end %>
+    </div>
+  <%% end %>
+</div>

data/lib/generators/calc_kit/templates/views/_saved_calculations.html.erb

@@ -0,0 +1,36 @@
+<%% if saved_calculations&.any? %>
+  <div class="mt-6">
+    <h3 class="text-sm font-semibold text-gray-500 mb-3">Recent Calculations</h3>
+    <div class="space-y-2">
+      <%% saved_calculations.each do |calculation| %>
+        <%%= ui_panel padding: :sm do %>
+          <div class="flex justify-between items-start gap-4 text-sm">
+            <div class="flex-1 min-w-0">
+              <div class="text-xs text-gray-400 mb-1">
+                <%%= calculation.created_at.to_fs(:short) %>
+                <%% if (version_warning = calc_kit_version_warning(calculation)) %>
+                  <%%= ui_badge label: "Outdated", variant: :warning %>
+                <%% end %>
+              </div>
+              <div class="flex flex-wrap gap-x-4 gap-y-1">
+                <%% calculation.outputs.each do |key, value| %>
+                  <span class="text-gray-700 dark:text-gray-300">
+                    <span class="text-gray-500"><%%= key.to_s.titleize %>:</span> <%%= value %>
+                  </span>
+                <%% end %>
+              </div>
+            </div>
+            <%% if defined?(reopen_calculation_path) %>
+              <div class="flex gap-2 shrink-0">
+                <%%= ui_button label: "Use", href: reopen_calculation_path(calculation), variant: :secondary, size: :sm %>
+              </div>
+            <%% end %>
+          </div>
+        <%% end %>
+      <%% end %>
+    </div>
+    <%% if defined?(calculations_path) %>
+      <%%= ui_button label: "View all", href: calculations_path, variant: :secondary, size: :sm %>
+    <%% end %>
+  </div>
+<%% end %>

data/lib/generators/calc_kit/templates/views/create.turbo_stream.erb

@@ -0,0 +1,3 @@
+<%%= turbo_stream.replace "calculator_result" do %>
+  <%%= render "result", calculator: @calculator, result: @result %>
+<%% end %>

data/lib/generators/calc_kit/templates/views/index.html.erb

@@ -0,0 +1,11 @@
+<%%= ui_page max_width: :lg do %>
+  <%%= ui_page_header title: "Calculators" %>
+
+  <%%= ui_grid cols: { default: 1, md: 2, lg: 3 } do %>
+    <%% CalcKit.all.each do |calculator_class| %>
+      <%%= ui_card_link href: calculator_path(slug: calculator_class.calculator_slug) do %>
+        <h2 class="text-lg font-semibold"><%%= calculator_class.calculator_name %></h2>
+      <%% end %>
+    <%% end %>
+  <%% end %>
+<%% end %>

data/lib/generators/calc_kit/templates/views/show.html.erb

@@ -0,0 +1,13 @@
+<%%= ui_page max_width: :lg do %>
+  <%%= ui_page_header title: @calculator_class.calculator_name %>
+
+  <%%= ui_panel do %>
+    <%%= render "form", calculator: @calculator %>
+  <%% end %>
+
+  <%%= render "result", calculator: @calculator, result: @result %>
+
+  <%% if defined?(@saved_calculations) && @saved_calculations&.any? %>
+    <%%= render "saved_calculations", saved_calculations: @saved_calculations %>
+  <%% end %>
+<%% end %>