onboardable 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 894b017b45b6b272a764dfd1ea6185c971ccabcbeee82ae0a195d41a0593b3af
-  data.tar.gz: f1a678edd9967f4e31d87f25cabd9d3da88c34a2c651a14c19e5881c13ac6b1c
+  metadata.gz: c7a359f33f51c9c573afe6ad4b438c7dbad0650ad3a665f5062ff0fb056a4e3d
+  data.tar.gz: d11d9642fae0159ef3055b1341ee6d6fffa9c25c7facf64244b98b6aed005bc4
 SHA512:
-  metadata.gz: b41f0070e487e5b687f31275da0a274e849f4758fcf539c60dfa91366b75885bcc9f91532002aa98919247fd184565c5f4fe43752b7fc087315c4bac36baa79d
-  data.tar.gz: 698e56a7902c725a3eb6062d3deb68874e18f854b025cd1cfbed7bd6dc0187034761d31c049c7d35febfe9f15adf3238a57f45adb3ce2d442070e6160ece637f
+  metadata.gz: 98d9460b91553ab1808e567989b7d05b6dac8fd4867a887461656e5202bbf60689cdeba416338f6b93c20e84e704721de31b77298197798542a72f64229472d5
+  data.tar.gz: 7d4c7a97f04bb61b0240f7c174f4a93b633f2af10396d547ae4537bce1eb734a05c98be14c547f0045e779bf011c153385d120cf7556553580b8075876d5bfc2

data/CHANGELOG.md

@@ -2,9 +2,13 @@
 
 ## [Unreleased]
 
+## [1.3.0] - 2024-06-10
+
+- Added option to calculate onboarding progress using a custom formula.
+
 ## [1.2.2] - 2024-06-03
 
-- Fix the issue with the default `#current_step` method.
+- Fixed the issue with the default `#current_step` method.
 
 ## [1.2.1] - 2024-06-01
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    onboardable (1.2.2)
+    onboardable (1.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -11,7 +11,7 @@ GEM
     docile (1.4.0)
     json (2.7.2)
     language_server-protocol (3.17.0.3)
-    parallel (1.24.0)
+    parallel (1.25.1)
     parser (3.3.2.0)
       ast (~> 2.4.1)
       racc
@@ -19,8 +19,8 @@ GEM
     rainbow (3.1.1)
     rake (13.2.1)
     regexp_parser (2.9.2)
-    rexml (3.2.8)
-      strscan (>= 3.0.9)
+    rexml (3.2.9)
+      strscan
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -47,21 +47,21 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.31.3)
       parser (>= 3.3.1.0)
-    rubocop-capybara (2.20.0)
+    rubocop-capybara (2.21.0)
       rubocop (~> 1.41)
-    rubocop-factory_bot (2.25.1)
+    rubocop-factory_bot (2.26.0)
       rubocop (~> 1.41)
     rubocop-performance (1.21.0)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (2.30.0)
+    rubocop-rspec (2.31.0)
       rubocop (~> 1.40)
       rubocop-capybara (~> 2.17)
       rubocop-factory_bot (~> 2.22)
       rubocop-rspec_rails (~> 2.28)
-    rubocop-rspec_rails (2.28.3)
+    rubocop-rspec_rails (2.29.0)
       rubocop (~> 1.40)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
@@ -84,7 +84,7 @@ DEPENDENCIES
   rubocop (~> 1.64, >= 1.64.1)
   rubocop-performance (~> 1.21)
   rubocop-rake (~> 0.6.0)
-  rubocop-rspec (~> 2.30)
+  rubocop-rspec (~> 2.31)
   simplecov (~> 0.22.0)
 
 BUNDLED WITH

data/README.md

@@ -1,7 +1,9 @@
 # 🚀 Onboardable
 
+![Gem Version](https://img.shields.io/gem/v/onboardable)
 ![Build](https://img.shields.io/github/actions/workflow/status/dmrAnderson/onboardable/ci.yml)
 ![Code Coverage](https://img.shields.io/coverallsCoverage/github/dmrAnderson/onboardable)
+![Gem Total Downloads](https://img.shields.io/gem/dt/onboardable)
 
 The Onboardable gem is a Ruby module designed to simplify and streamline the
 process of managing and navigating through a series of steps or stages within
@@ -140,13 +142,36 @@ that allow step navigation and state verification:
 
 1. **Monitor Progress**
 
-   Calculate the progress or completion percentage of the onboarding process
-   to provide users with an indication of how far they have progressed.
+   - Calculate the progress or completion percentage of the onboarding process
+     to provide users with an indication of how far they have progressed.
 
    ```ruby
    onboarding.progress # Returns the completion percentage
    ```
 
+   - To customize the progress calculation formula, define a lambda function
+     that takes the current step index and the total number of steps as arguments.
+
+    ```ruby
+    CALCULATION = ->(step_index, steps_size) { step_index + steps_size }
+    onboarding.progress(CALCULATION)
+    ```
+
+   - Alternatively, set the custom progress calculation formula during the
+     onboarding definition to automatically calculate the progress.
+
+    ```ruby
+    class User
+      include Onboardable
+
+      CALCULATION = ->(step_index, steps_size) { step_index + steps_size }
+
+      has_onboarding progress_calculation: CALCULATION do
+        # ...
+      end
+    end
+    ```
+
 1. **Access Current Step Details**
 
    Retrieve details about the current step, which can include the name,

data/lib/onboardable/list/base.rb

@@ -6,6 +6,8 @@ module Onboardable
     class Base
       include Navigation
 
+      PROGRESS_CALCULATION = ->(step_index, steps_size) { (step_index.to_f / steps_size) * 100 }
+
       # @return [Array<Step>] The steps in the list.
       attr_reader :steps
 
@@ -16,20 +18,27 @@ module Onboardable
       #
       # @param steps [Array<Step>] An array of steps comprising the onboarding process.
       # @param current_step [Step] The step currently active in the process.
-      def initialize(steps, current_step)
+      # @param options [Hash] An options hash for the list.
+      def initialize(steps, current_step, options = {})
         self.steps = steps
         self.current_step = current_step
+        self.options = options
       end
 
       # Calculates and returns the onboarding progress as a percentage.
       #
-      # @return [Float] The completion percentage of the onboarding process.
-      def progress
-        (step_index(current_step).to_f / steps.size) * 100
+      # @param progress_calculation [Proc, nil] An optional custom calculation for progress.
+      # @return [Float] The percentage of steps completed in the onboarding process.
+      def progress(progress_calculation = nil)
+        progress_calculation ||= options.fetch(:progress_calculation, PROGRESS_CALCULATION)
+        Float(progress_calculation[step_index(current_step), steps.size])
       end
 
       private
 
+      # @return [Hash] The options hash for the list.
+      attr_reader :options
+
       # Sets and validates the steps array, ensuring it is an Array of Step objects.
       #
       # @param steps [Array<Step>] The steps to be assigned to the list.
@@ -49,6 +58,14 @@ module Onboardable
         end
       end
 
+      # Sets and validates the options hash, ensuring it is a Hash object.
+      #
+      # @param options [Hash] The options to be assigned to the list.
+      # @return [Hash] The assigned options.
+      def options=(options)
+        @options = Hash(options).transform_keys(&:to_sym).freeze
+      end
+
       # Determines the index of a given step in the list, ensuring the step exists.
       #
       # @param raw_step [Step] The step for which the index is requested.

data/lib/onboardable/list/builder.rb

@@ -6,15 +6,19 @@ module Onboardable
     class Builder
       include Utils::Warnings
 
-      # @return [Hash] A hash where keys are step names and values are Step objects.
-      attr_reader :steps
+      # Stores the steps added to the builder.
+      #
+      # @return [Hash] A hash of steps added to the builder.
+      def steps
+        options[__method__] ||= {}
+      end
 
       # @return [Step] The current step in the building process, defaulting to the first added step.
       attr_accessor :current_step
 
       # Initializes a new instance of ListBuilder.
-      def initialize
-        self.steps = {}
+      def initialize(options = {})
+        self.options = options
       end
 
       # Creates a new Step object and adds it to the builder.
@@ -38,7 +42,7 @@ module Onboardable
 
       # Constructs a new List object from the steps added to the builder.
       #
-      # @param current_step_name [String] The name of the current step.
+      # @param current_step_name [String, nil] The name of the current step.
       # @return [Base] A new List object initialized with the steps and the specified current step.
       def build(current_step_name = nil)
         Base.new(convert_to_steps!, convert_to_step!(current_step_name || current_step.name))
@@ -46,6 +50,16 @@ module Onboardable
 
       private
 
+      # @return [Hash] The options hash for the builder.
+      attr_reader :options
+
+      # Sets the options hash for the builder.
+      #
+      # @param options [Hash] The options hash to be set.
+      def options=(options)
+        @options = Hash(options)
+      end
+
       # Adds a step to the builder.
       #
       # @param step [Step] The step to be added.
@@ -59,13 +73,6 @@ module Onboardable
         step.tap { self.current_step ||= step }
       end
 
-      # Assigns a hash of steps to the builder.
-      #
-      # @param raw_steps [Hash] The hash of steps to be assigned.
-      def steps=(raw_steps)
-        @steps = Hash(Hash.try_convert(raw_steps))
-      end
-
       # Converts the internal hash of steps to an array of Step objects.
       #
       # @return [Array<Step>] An array of steps.

data/lib/onboardable/step.rb

@@ -14,28 +14,42 @@ module Onboardable
     STATUSES = [PENDING_STATUS, CURRENT_STATUS, COMPLETED_STATUS].freeze
 
     class << self
-      def try_convert(value)
-        return unless value.respond_to?(CONVERSION_METHOD)
+      # Attempts to convert a class to a Step object using a specified conversion method.
+      #
+      # @param klass [Class] The class to convert to a Step
+      # @return [Step, nil] The converted Step object, or nil if the class does not respond to the conversion method
+      def try_convert(klass)
+        return unless klass.respond_to?(CONVERSION_METHOD)
 
-        value.public_send(CONVERSION_METHOD).then do |step|
-          step.is_a?(Step) ? step : raise(StepConversionError.new(value, step))
+        klass.public_send(CONVERSION_METHOD).then do |step|
+          step.is_a?(Step) ? step : conversion_error!(klass, step)
         end
       end
+
+      private
+
+      # Raises an error for a failed conversion attempt.
+      #
+      # @param klass [Class] The class that failed to convert
+      # @raise [StepConversionError] Raises an error for a failed conversion attempt
+      def conversion_error!(klass, step)
+        raise StepConversionError.new(klass, step)
+      end
     end
 
-    # @return [String] the name of the step
+    # @return [String] The name of the step
     attr_reader :name
 
-    # @return [Hash] custom data associated with the step
+    # @return [Hash] Custom data associated with the step
     attr_reader :data
 
-    # @return [Symbol] the current status of the step
+    # @return [Symbol] The current status of the step
     attr_reader :status
 
     # Initializes a new Step with a name, optional custom data, and a default status.
     #
-    # @param name [String] the name of the step
-    # @param data [Hash] the custom data associated with the step, defaults to an empty hash
+    # @param name [String] The name of the step
+    # @param data [Hash] The custom data associated with the step, defaults to an empty hash
     def initialize(name, data = {})
       self.name = name
       self.data = data
@@ -46,7 +60,7 @@ module Onboardable
       # @!method {status_method}?
       # Checks if the step is in a specific status.
       #
-      # @return [Boolean] true if the step is currently in the {status_method} status, false otherwise.
+      # @return [Boolean] True if the step is currently in the {status_method} status, false otherwise.
       define_method :"#{status_method}?" do
         status == status_method
       end
@@ -54,24 +68,23 @@ module Onboardable
 
     # Compares this step to another to determine if they are equivalent, based on the step name.
     #
-    # @param other [Step] the step to compare with
-    # @return [Boolean] true if both steps have the same name, false otherwise
+    # @param other [Step] The step to compare with
+    # @return [Boolean] True if both steps have the same name, false otherwise
     def ==(other)
       to_str == other.to_str
     end
 
     # Provides a string representation of the step, using its name.
     #
-    # @return [String] the name of the step
+    # @return [String] The name of the step
     def to_str
       name
     end
 
     # Updates the status of the step based on a specified comparison result.
     #
-    # @param comparison_result [Integer] the result of a comparison with the current step (-1, 0, or 1)
-    # @return [Symbol] the new status of the step
-    # @raise [ComparisonResultError] if the comparison result is not -1, 0, or 1
+    # @param comparison_result [Integer] The result of a comparison with the current step (-1, 0, or 1)
+    # @return [Symbol] The new status of the step
     def update_status!(comparison_result)
       self.status = case comparison_result
                     when -1 then COMPLETED_STATUS
@@ -84,14 +97,14 @@ module Onboardable
 
     # Sets the name of the step, ensuring it is a valid String.
     #
-    # @param raw_name [String] the raw name of the step
+    # @param raw_name [String] The raw name of the step
     def name=(raw_name)
-      @name = String.new(String.try_convert(raw_name)).freeze
+      @name = String.new(raw_name).freeze
     end
 
     # Sets the status of the step.
     #
-    # @param raw_status [Symbol] the new status of the step
+    # @param raw_status [Symbol] The new status of the step
     def status=(raw_status)
       STATUSES.include?(raw_status) || raise(StepStatusError.new(raw_status, STATUSES))
 
@@ -100,15 +113,15 @@ module Onboardable
 
     # Sets the custom data for the step, ensuring it is a valid Hash.
     #
-    # @param raw_data [Hash] the raw custom data
+    # @param raw_data [Hash] The raw custom data
     def data=(raw_data)
-      @data = Hash(Hash.try_convert(raw_data)).freeze
+      @data = Hash(raw_data).freeze
     end
 
     # Raises an error for an invalid comparison result.
     #
-    # @param comparison_result [Integer] the invalid comparison result
-    # @raise [ComparisonResultError] raises an error for an invalid comparison result
+    # @param comparison_result [Integer] The invalid comparison result
+    # @raise [ComparisonResultError] Raises an error for an invalid comparison result
     def comparison_result_error!(comparison_result)
       raise ComparisonResultError.new(comparison_result, (-1..1).to_a)
     end

data/lib/onboardable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Onboardable
-  VERSION = '1.2.2'
+  VERSION = '1.3.0'
 end

data/lib/onboardable.rb

@@ -21,21 +21,19 @@ module Onboardable
 
   # Class methods for managing the onboarding process, added to the class that includes the Onboardable module.
   module ClassMethods
-    # Retrieves or initializes a ListBuilder for onboarding steps at the class level.
-    #
-    # @return [List::Builder] The ListBuilder associated with the class.
-    def list_builder
-      @list_builder ||= List::Builder.new
-    end
+    # @return [List::Builder] The ListBuilder for configuring onboarding steps.
+    attr_accessor :list_builder
 
     # Configures onboarding steps via a ListBuilder with a provided block.
     #
+    # @param options [Hash] Optional configuration options for the ListBuilder.
     # @yield [List::Builder] Executes block in the context of List::Builder.
     # @return [Step] The current step in the building process.
-    def list_builder=(&block)
+    def onboarding=(options = {}, &block)
+      self.list_builder = List::Builder.new(options)
       list_builder.instance_eval(&block)
     end
-    alias has_onboarding list_builder=
+    alias has_onboarding onboarding=
 
     # Builds the onboarding list and optionally sets the current step.
     #

data/onboardable.gemspec

@@ -44,7 +44,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop', '~> 1.64', '>= 1.64.1'
   spec.add_development_dependency 'rubocop-performance', '~> 1.21'
   spec.add_development_dependency 'rubocop-rake', '~> 0.6.0'
-  spec.add_development_dependency 'rubocop-rspec', '~> 2.30'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.31'
   spec.add_development_dependency 'simplecov', '~> 0.22.0'
 
   spec.metadata['rubygems_mfa_required'] = 'true'

data/sig/onboardable/list/base.rbs

@@ -1,18 +1,22 @@
 module Onboardable
   module List
     class Base
+      PROGRESS_CALCULATION: Proc
+
       attr_reader steps: Array[Step]
       attr_reader current_step: Step
 
       def initialize: (Array[Step], Step) -> instance
 
-      def progress: -> Float
+      def progress: (Proc?) -> Float
 
       private
 
       attr_writer steps: Array[Step]
       attr_writer current_step: Step
 
+      attr_accessor options: Hash[Symbol, untyped]
+
       def step_error!: (Step) -> void
 
       def step_index: (Step)-> Integer

data/sig/onboardable/list/builder.rbs

@@ -4,7 +4,7 @@ module Onboardable
       attr_reader steps: Hash[String, Step]
       attr_accessor current_step: Step
 
-      def initialize: () -> Hash[String, Step]
+      def initialize: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
       def create_step: (String, Hash[Symbol, untyped]) -> Step
       alias step create_step
@@ -16,7 +16,7 @@ module Onboardable
 
       private
 
-      attr_writer steps: Hash[String, Step]
+      attr_accessor options: Hash[Symbol, untyped]
 
       def add_step: (Step) -> Step
 

data/sig/onboardable/step.rbs

@@ -7,7 +7,9 @@ module Onboardable
     DEFAULT_STATUS: Symbol
     STATUSES: Array[Symbol]
 
-    def self.try_convert: -> Step?
+    def self.try_convert: (Class) -> Step?
+
+    def self.conversion_error!: (Class, untyped) -> void
 
     attr_reader name: String
     attr_reader data: Hash[Symbol, untyped]

data/sig/onboardable.rbs

@@ -3,10 +3,10 @@ module Onboardable
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 
   module ClassMethods
-    attr_reader list_builder: List::Builder
+    attr_accessor list_builder: List::Builder
 
-    def list_builder=: () { () -> List::Builder } -> Step
-    alias has_onboarding list_builder=
+    def onboarding=: (Hash[Symbol, untyped]) { () -> List::Builder } -> Step
+    alias has_onboarding onboarding=
 
     def onboarding: (String?) -> List::Base
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: onboardable
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Artem Skrynnyk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2024-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -98,14 +98,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.30'
+        version: '2.31'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.30'
+        version: '2.31'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement