metricdeck 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7f573a7a2e2bb3711b03137e5fb248eed220a12175d15d9e040d0844d69bbc1
+  data.tar.gz: fc0d9ef9f8b3d918ef3ddd6868a829d472a9145d0cd95af841f5b857d8f81ca1
+SHA512:
+  metadata.gz: 7c3840a0e01c4944a39e7c71693d408b2d258a691c5c70d0574863707b863ed9a693db4aec4ccd86bd00a88a7f7310113be428e52f23a32676b4da553f6e54b3
+  data.tar.gz: b8a712c7d62e113f4577e71ce8599cef4bc3854038024d49c14e838b02d61e5ce57b630942ccdcf139e81e83c5ce0aa18324e5b9981b1555f84be3dc2acb5b73

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [0.1.4](https://github.com/shqear93/metricdeck/compare/metricdeck/v0.1.3...metricdeck/v0.1.4) (2026-05-31)
+
+
+### Bug Fixes
+
+* update gemspec homepage to correct repo URL ([2b9ea5b](https://github.com/shqear93/metricdeck/commit/2b9ea5bb9d65ea270d9914165c11dd476ded6285))
+
+## [0.1.3](https://github.com/shqear93/metricdeck/compare/metricdeck/v0.1.2...metricdeck/v0.1.3) (2026-05-29)
+
+
+### Bug Fixes
+
+* verify end-to-end automated release pipeline ([2ea3800](https://github.com/shqear93/metricdeck/commit/2ea3800a9e37c299f43d6c4fc18d226f5034a184))
+
+## [0.1.2](https://github.com/shqear93/metricdeck/compare/metricdeck/v0.1.1...metricdeck/v0.1.2) (2026-05-29)
+
+
+### Bug Fixes
+
+* bound rails dependency to avoid open-ended warning ([ff74091](https://github.com/shqear93/metricdeck/commit/ff740911cf843e1c3024db98face4c631101547d))
+
+## [0.1.1](https://github.com/shqear93/metricdeck/compare/metricdeck-v0.1.0...metricdeck/v0.1.1) (2026-05-29)
+
+
+### Bug Fixes
+
+* include release-please manifest in gem files ([6aff160](https://github.com/shqear93/metricdeck/commit/6aff1609e0fce806f1af6dfd392b521dd0a4dac5))
+
+## [0.1.0] - 2026-05-27
+
+- Initial release as **metricdeck**
+- Extracted metric card framework from Athar EMS people service
+- MetricCard value object with trend/comparison support
+- BaseCalculator module with validate + perform interface
+- CardHelpers with percentage_change, determine_trend, create_metric_card
+- DateHelpers with parse_date, calculate_previous_period, generate_comparison_text
+- MetricCardService with auto-discovery of calculators by namespace
+- Rails generator for new calculators

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Athar Association
+
+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,91 @@
+# metricdeck
+
+[![CI](https://github.com/shqear93/metricdeck/actions/workflows/ci.yml/badge.svg)](https://github.com/shqear93/metricdeck/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/metricdeck.svg)](https://rubygems.org/gems/metricdeck)
+
+A pluggable metric card framework for Ruby on Rails applications.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'metricdeck'
+```
+
+## Usage
+
+### 1. Create a calculator
+
+```ruby
+# app/metrics/calculators/users_calculator.rb
+module Metrics
+  module Calculators
+    class UsersCalculator
+      include Metricdeck::Calculators::BaseCalculator
+      include Metricdeck::Helpers::CardHelpers
+
+      def validate_context(context)
+        # optional validation
+      end
+
+      def perform_calculation(context)
+        current = User.active.count
+        previous = User.active.where('created_at <= ?', 1.month.ago).count
+
+        create_metric_card(
+          card_id,
+          value: current,
+          current: current,
+          previous: previous
+        )
+      end
+    end
+  end
+end
+```
+
+### 2. Fetch metric cards
+
+```ruby
+service = Metricdeck::MetricCardService.new(namespace: Metrics::Calculators)
+cards = service.get_cards({ employee_id: 42 })
+```
+
+### 3. Generate a calculator
+
+```bash
+rails g metricdeck:calculator users
+```
+
+## I18n
+
+Add translations under:
+
+```yaml
+en:
+  metricdeck:
+    cards:
+      users:
+        title: "Active Users"
+        unit: "users"
+    comparisons:
+      previous_period: "vs previous period"
+      last_month: "vs last month"
+      last_year: "vs last year"
+```
+
+## Migrating from Athar EMS People Service
+
+If you're migrating from the internal `Statistics` module in the Athar EMS people service:
+
+1. Replace `Statistics::Calculators::BaseCalculator` with `Metricdeck::Calculators::BaseCalculator`
+2. Replace `Statistics::Helpers::CardHelpers` with `Metricdeck::Helpers::CardHelpers`
+3. Replace `Statistics::Helpers::DateHelpers` with `Metricdeck::Helpers::DateHelpers`
+4. Replace `Statistics::MetricCardService` with `Metricdeck::MetricCardService`
+5. Replace `Statistics::MetricCard` with `Metricdeck::MetricCard`
+6. Update i18n keys from `statistics.*` to `metricdeck.*`
+7. Pass your calculator namespace explicitly:
+   ```ruby
+   service = Metricdeck::MetricCardService.new(namespace: Statistics::Calculators)
+   ```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/generators/metricdeck/calculator/calculator_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Metricdeck
+  module Generators
+    class CalculatorGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a new metric calculator'
+
+      def create_calculator_file
+        template 'calculator.rb.tt', "app/metrics/calculators/#{file_name}_calculator.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Metrics
+  module Calculators
+    class <%= class_name %>Calculator
+      include Metricdeck::Calculators::BaseCalculator
+      include Metricdeck::Helpers::CardHelpers
+
+      def validate_context(context)
+        # Add validation logic here
+        # Example:
+        # raise ArgumentError, "Missing required context: employee_id" unless context[:employee_id].present?
+      end
+
+      def perform_calculation(context)
+        # Calculate current and previous values
+        current = 0
+        previous = 0
+
+        create_metric_card(
+          card_id,
+          value: current,
+          current: current,
+          previous: previous
+        )
+      end
+    end
+  end
+end

data/lib/metricdeck/calculators/base_calculator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  module Calculators
+    module BaseCalculator
+      def calculate(context)
+        validate_context(context)
+        perform_calculation(context)
+      end
+
+      def perform_calculation(_context)
+        raise NotImplementedError, "#{self.class} must implement #perform_calculation"
+      end
+
+      def card_id
+        self.class.name.demodulize.underscore.sub(/_calculator$/, '')
+      end
+
+      protected
+
+      def validate_context(_context)
+        # Override in subclasses
+      end
+    end
+  end
+end

data/lib/metricdeck/helpers/card_helpers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  module Helpers
+    module CardHelpers
+      def calculate_percentage_change(current, previous)
+        return 0 if previous.to_f.zero?
+
+        ((current.to_f - previous.to_f) / previous.to_f * 100).round(1)
+      end
+
+      def determine_trend(current, previous)
+        return 'neutral' if previous.to_f.zero? || current == previous
+
+        current > previous ? 'up' : 'down'
+      end
+
+      def create_metric_card(id, value:, current:, previous:, title_key: nil, unit_key: nil,
+                             comparison_key: nil, comparison_text: nil)
+        card_key = id.to_s
+
+        title = resolve_title(card_key, title_key)
+        unit = resolve_unit(card_key, unit_key)
+        comparison_text ||= resolve_comparison_text(card_key, comparison_key)
+
+        percentage_change = calculate_percentage_change(current, previous)
+        trend = determine_trend(current, previous)
+
+        Metricdeck::MetricCard.new(
+          id: id,
+          title: title,
+          value: value.to_s,
+          unit: unit,
+          comparison_percentage: percentage_change,
+          trend: trend,
+          comparison_text: comparison_text
+        )
+      end
+
+      private
+
+      def resolve_title(card_key, title_key)
+        key = title_key || "metricdeck.cards.#{card_key}.title"
+        I18n.t(key, default: card_key.humanize)
+      end
+
+      def resolve_unit(card_key, unit_key)
+        if unit_key.is_a?(Symbol)
+          I18n.t("metricdeck.units.#{unit_key}", default: '')
+        elsif unit_key.present?
+          I18n.t(unit_key, default: '')
+        else
+          I18n.t("metricdeck.cards.#{card_key}.unit", default: '')
+        end
+      end
+
+      def resolve_comparison_text(card_key, comparison_key)
+        default = I18n.t('metricdeck.comparisons.previous_period', default: 'vs previous period')
+        if comparison_key.is_a?(Symbol)
+          I18n.t("metricdeck.comparisons.#{comparison_key}", default: default)
+        elsif comparison_key.present?
+          I18n.t(comparison_key, default: default)
+        else
+          I18n.t("metricdeck.cards.#{card_key}.comparison", default: default)
+        end
+      end
+    end
+  end
+end

data/lib/metricdeck/helpers/date_helpers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  module Helpers
+    module DateHelpers
+      def parse_date_with_formats(date_str)
+        return nil if date_str.blank?
+        return date_str if date_str.is_a?(Date)
+
+        formats = ['%d-%m-%Y', '%Y-%m-%d', '%m/%d/%Y', '%d/%m/%Y']
+
+        formats.each do |format|
+          return Date.strptime(date_str.to_s, format)
+        rescue Date::Error
+          next
+        end
+
+        begin
+          Date.parse(date_str.to_s)
+        rescue Date::Error
+          nil
+        end
+      end
+
+      def calculate_previous_period(start_date, end_date, comparison_period = :previous)
+        period_length = (end_date - start_date).to_i + 1
+
+        case comparison_period.to_sym
+        when :month, :last_month
+          prev_start_date = start_date.prev_month
+          prev_end_date = [end_date.prev_month, prev_start_date.end_of_month].min
+        when :year, :last_year
+          prev_start_date = start_date.prev_year
+          prev_end_date = end_date.prev_year
+        else
+          prev_start_date = start_date - period_length.days
+          prev_end_date = end_date - period_length.days
+        end
+
+        [prev_start_date, prev_end_date]
+      end
+
+      def generate_comparison_text(comparison_period)
+        period = comparison_period.to_sym if comparison_period.respond_to?(:to_sym)
+
+        comparison_key = case period
+                         when :month, :last_month
+                           :last_month
+                         when :year, :last_year
+                           :last_year
+                         else
+                           :previous_period
+                         end
+
+        I18n.t("metricdeck.comparisons.#{comparison_key}")
+      end
+    end
+  end
+end

data/lib/metricdeck/metric_card.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  class MetricCard
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+    include ActiveModel::Serialization
+
+    attribute :id, :string
+    attribute :title, :string
+    attribute :value, :string
+    attribute :unit, :string
+    attribute :comparison_percentage, :float
+    attribute :trend, :string
+    attribute :comparison_text, :string
+
+    def initialize(attributes = {})
+      super
+    end
+
+    def comparison
+      {
+        'percentage' => comparison_percentage,
+        'trend' => trend,
+        'text' => comparison_text
+      }
+    end
+
+    def as_json(_options = nil)
+      attributes.compact.merge('comparison' => comparison)
+    end
+  end
+end

data/lib/metricdeck/metric_card_service.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  class MetricCardService
+    attr_reader :namespace
+
+    def initialize(namespace: nil)
+      @namespace = namespace || default_namespace
+    end
+
+    def get_cards(context, card_types = nil)
+      calculators = available_calculators
+
+      calculators = calculators.select { |c| card_types.include?(c.card_id.to_sym) } if card_types.present?
+
+      calculators.map { |calculator| calculator.calculate(context) }
+    end
+
+    def available_calculators
+      calculators = []
+
+      namespace.constants.each do |const_name|
+        const = namespace.const_get(const_name)
+
+        next unless const.is_a?(Class) &&
+                    const.included_modules.include?(Metricdeck::Calculators::BaseCalculator) &&
+                    const_name.to_s.end_with?('Calculator')
+
+        calculators << const.new
+      end
+
+      calculators
+    end
+
+    def available_card_types
+      available_calculators.map { |c| c.card_id.to_sym }
+    end
+
+    private
+
+    def default_namespace
+      if Object.const_defined?(:Metrics) && ::Metrics.const_defined?(:Calculators)
+        ::Metrics::Calculators
+      else
+        raise ArgumentError,
+              'No calculator namespace provided and Metrics::Calculators is not defined. ' \
+              'Pass namespace: MyApp::Metrics::Calculators to MetricCardService.new'
+      end
+    end
+  end
+end

data/lib/metricdeck/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Metricdeck
+  VERSION = '0.1.4'
+end

data/lib/metricdeck.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'active_model'
+require 'active_support/all'
+
+module Metricdeck
+  class Error < StandardError; end
+
+  require_relative 'metricdeck/version'
+  require_relative 'metricdeck/metric_card'
+  require_relative 'metricdeck/calculators/base_calculator'
+  require_relative 'metricdeck/helpers/card_helpers'
+  require_relative 'metricdeck/helpers/date_helpers'
+  require_relative 'metricdeck/metric_card_service'
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: metricdeck
+version: !ruby/object:Gem::Version
+  version: 0.1.4
+platform: ruby
+authors:
+- Athar Team
+bindir: bin
+cert_chain: []
+date: 2026-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: A calculator registry that produces standardized metric cards with trends,
+  comparisons, and i18n labels.
+email:
+- info@athar.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/metricdeck/calculator/calculator_generator.rb
+- lib/generators/metricdeck/calculator/templates/calculator.rb.tt
+- lib/metricdeck.rb
+- lib/metricdeck/calculators/base_calculator.rb
+- lib/metricdeck/helpers/card_helpers.rb
+- lib/metricdeck/helpers/date_helpers.rb
+- lib/metricdeck/metric_card.rb
+- lib/metricdeck/metric_card_service.rb
+- lib/metricdeck/version.rb
+homepage: https://github.com/shqear93/metricdeck
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/shqear93/metricdeck
+  source_code_uri: https://github.com/shqear93/metricdeck
+  changelog_uri: https://github.com/shqear93/metricdeck/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Pluggable metric card framework for Rails
+test_files: []