onboardable 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aeeceb88e43c0cefe319f2fa5e301618b0d4b3a57d34edc507298e752cd52ec
-  data.tar.gz: d29c89bf6488afe8d46f8f948bdc892b40172953ccf8bb3f5cf1d8191b7ad48a
+  metadata.gz: 5190ba93a0d09c427d6314bd1e7645ca8052406683fd9bc8f8ee90a7d0ba2386
+  data.tar.gz: 3aa3d7073ecba0ab36c136584a48c5296e40c98d80fdab15b95cf8de7d014040
 SHA512:
-  metadata.gz: 053a72f2dab37f639b258e74f4f984d688af673dd43c3771b583f7ba46da4e3f9c28d64fb4972642669d266711b1b811c662e16718f2d32929a8b4612dc605bb
-  data.tar.gz: abd9ce8f2775ade5edd1a3b2450f0c873a7e9a5156135c43ed4a80bd5a46a156d94a44dac14b0ade16d32f220b4e14511a15a19ca36af8d71d90425fb4c59179
+  metadata.gz: 5b5248e51f51c217d8ddaeb2171b4a653bf291e1c02302701b1a02fae9175430ded3100e2e87e5f95514d9e1676cb159fc3c939f49a218f7f9b61cd9ba01b39d
+  data.tar.gz: 83a10458cd15031209a7ceeb7f8dec8a46de0c1af1b2328f8d142a41739c0983a62e4a11729761465f3a36dcdf0e9e3b90df20732de6d22d5a50cb91c48dc0ef

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [1.2.0] - 2024-05-25
+
+- Added `#second_step?` method to check if the target step is the second step.
+- Added `#prev_step?` method to check if the target step is the previous step.
+- Added `#current_step?` method to check if the target step is the current step.
+
+## [1.1.1] - 2024-05-21
+
+- Added `onboarding` class method to define the onboarding steps.
+- Added [documentation link](https://rubydoc.info/gems/onboardable) to gemspec.
+
 ## [1.1.0] - 2024-05-21
 
 - Introduced `step_from` method for adding steps from external sources.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    onboardable (1.1.0)
+    onboardable (1.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -34,7 +34,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.63.5)
+    rubocop (1.64.0)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -81,7 +81,7 @@ DEPENDENCIES
   onboardable!
   rake (~> 13.2, >= 13.2.1)
   rspec (~> 3.13)
-  rubocop (~> 1.63, >= 1.63.5)
+  rubocop (~> 1.64)
   rubocop-performance (~> 1.21)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.29, >= 2.29.2)

data/README.md

@@ -41,27 +41,15 @@ project as per the installation guide provided earlier.
      include Onboardable
 
      has_onboarding do
-       # Welcome step with a greeting message.
        step 'welcome', message: 'Welcome to your new account!'
-
-       # Account setup step for credentials.
        step 'account_setup', task: 'Create credentials'
-
-       # Profile completion step to add photo and bio.
-       step 'profile_completion', task: 'Add a photo and bio'
-
-       # Confirmation step to verify details before completion.
-       step 'confirmation', prompt: 'Confirm your details'
-
-       # Use `step_from` to add steps from external sources for reusability.
+       step 'confirmation'
        step_from ExternalStepProvider
      end
    end
 
-   # External class for providing a reusable onboarding step
    class ExternalStepProvider
-     # Define a method to return an onboarding step
-     def self.to_onboardable_step
+     def self.to_onboarding_step
        Onboardable::Step.new('external_step', info: 'This is an external step.')
      end
    end
@@ -87,6 +75,15 @@ that allow step navigation and state verification:
    onboarding = User.new.onboarding
    ```
 
+1. **Check order of steps**
+
+   Determine the order of steps in the onboarding process to ensure
+   that the sequence is correct and that the steps are defined as expected.
+
+   ```ruby
+   onboarding.steps # Returns the list of steps
+   ```
+
 1. **Navigating Through Steps**
 
    Navigate through the onboarding steps using the navigation methods provided.
@@ -118,8 +115,13 @@ that allow step navigation and state verification:
    to manage UI elements like 'Next' or 'Back' buttons appropriately.
 
    ```ruby
-   onboarding.first_step? # Is the first step?
-   onboarding.last_step?  # Is the last step?
+   step = onboarding.steps.sample # Random step from the list
+
+   onboarding.first_step?(step)   # Is the first step?
+   onboarding.last_step?(step)    # Is the last step?
+   onboarding.current_step?(step) # Is the current step?
+   onboarding.second_step?(step)  # Is the second step?
+   onboarding.prev_step?(step)    # Is the previous step?
    ```
 
 1. **Monitor Progress**

data/lib/onboardable/errors.rb

@@ -36,8 +36,8 @@ module Onboardable
   end
 
   # Error raised when an invalid step is encountered within the onboarding process.
-  class InvalidStepError < Error
-    # Initializes a new InvalidStepError with details about the issue.
+  class StepError < Error
+    # Initializes a new StepError with details about the issue.
     #
     # @param step [String] The invalid step that triggered the error.
     # @param expected_steps [Array<String>] The list of valid steps expected at this point.
@@ -78,4 +78,15 @@ module Onboardable
       super("Currently `#{step}` the first step. Available steps are: `#{expected_steps.join('`, `')}`.")
     end
   end
+
+  # Error raised when an invalid status is encountered for a step.
+  class StepStatusError < Error
+    # Initializes a new StepStatusError with details about the issue.
+    #
+    # @param status [Symbol] The invalid status that triggered the error.
+    # @param expected_statuses [Array<Symbol>] The list of valid statuses expected.
+    def initialize(status, expected_statuses)
+      super("Invalid status: `#{status}`. Must be one of: `#{expected_statuses.join('`, `')}`.")
+    end
+  end
 end

data/lib/onboardable/list/base.rb

@@ -6,10 +6,10 @@ module Onboardable
     class Base
       include Navigation
 
-      # @return [Array<Step>] the steps in the list
+      # @return [Array<Step>] The steps in the list.
       attr_reader :steps
 
-      # @return [Step] the current step in the list
+      # @return [Step] The current step in the list.
       attr_reader :current_step
 
       # Initializes a new instance of List with steps and a current step.
@@ -25,7 +25,7 @@ module Onboardable
       #
       # @return [Float] The completion percentage of the onboarding process.
       def progress
-        (step_index!(current_step).to_f / steps.size) * 100
+        (step_index(current_step).to_f / steps.size) * 100
       end
 
       private
@@ -33,6 +33,7 @@ module Onboardable
       # 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.
+      # @return [Array<Step>] The assigned steps.
       def steps=(steps)
         @steps = Array(Array.try_convert(steps)).freeze
       end
@@ -40,19 +41,38 @@ module Onboardable
       # Updates the current step and recalibrates the status of all steps in the list.
       #
       # @param raw_current_step [Step] The new current step to set.
+      # @return [Step] The updated current step.
       def current_step=(raw_current_step)
-        current_step_index = step_index!(raw_current_step)
-        steps.each_with_index { |step, index| step.update_status!(index <=> current_step_index) }
-        @current_step = steps.fetch(current_step_index)
+        step_index(raw_current_step).then do |index|
+          update_each_step_status(index)
+          @current_step = steps.fetch(index)
+        end
       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.
       # @return [Integer] The index of the step within the list.
-      # @raise [InvalidStepError] Raises an error if the step does not exist in the list.
-      def step_index!(raw_step)
-        steps.index { |step| step == raw_step } || raise(InvalidStepError.new(raw_step.to_str, steps.map(&:to_str)))
+      def step_index(raw_step)
+        steps.index { |step| step == raw_step } || step_error!(raw_step)
+      end
+
+      # Updates the status of each step in the list based on the current step index.
+      #
+      # @param current_step_index [Integer] The index of the current step in the list.
+      # @return [Array<Step>] The updated steps array.
+      def update_each_step_status(current_step_index)
+        steps.each_with_index do |step, index|
+          step.update_status!(index <=> current_step_index)
+        end
+      end
+
+      # Raises a StepError indicating an invalid step was encountered.
+      #
+      # @param raw_step [Step] The step that triggered the error.
+      # @raise [StepError] Raises an error if the step does not exist in the list.
+      def step_error!(raw_step)
+        raise StepError.new(raw_step.to_str, steps.map(&:to_str))
       end
     end
   end

data/lib/onboardable/list/builder.rb

@@ -30,19 +30,18 @@ module Onboardable
       # Converts a class to a Step object and adds it to the builder.
       #
       # @param klass [Class] The class to be converted to a step.
-      # @raise [UndefinedMethodError] if the conversion method is not defined for the class.
+      # @return [Step] The converted step.
+      # @raise [UndefinedMethodError] If the conversion method is not defined for the class.
       def create_step_from!(klass)
-        Step.try_convert(klass).tap do |step|
-          add_step(step || raise(UndefinedMethodError.new(klass, Step::CONVERSION_METHOD)))
-        end
+        (Step.try_convert(klass) || undefined_method_error!(klass)).tap { |step| add_step(step) }
       end
       alias step_from create_step_from!
 
       # Constructs a new List object from the steps added to the builder.
       #
-      # @param current_step_name [String] The name of the step to mark as current in the built list.
+      # @param current_step_name [String, nil] The name of the step to mark as current in the built list. Can be nil.
       # @return [Base] A new List object initialized with the steps and the specified current step.
-      # @raise [EmptyStepsError] if no steps have been added to the builder.
+      # @raise [EmptyStepsError] If no steps have been added to the builder.
       def build!(current_step_name)
         Base.new(convert_to_steps!, convert_to_step!(current_step_name || current_step.name))
       end
@@ -52,13 +51,14 @@ module Onboardable
       # Adds a step to the builder.
       #
       # @param step [Step] The step to be added.
+      # @return [Step] The added step.
       def add_step(step)
-        step.name.then do |name|
+        step.tap do
+          name = step.name
           warn_about_override(name) if steps.key?(name)
           steps[name] = step
+          self.current_step ||= step
         end
-
-        self.current_step ||= step
       end
 
       # Assigns a hash of steps to the builder.
@@ -73,18 +73,24 @@ module Onboardable
       # @return [Array<Step>] An array of steps.
       # @raise [EmptyStepsError] Raises if there are no steps to convert.
       def convert_to_steps!
-        raise EmptyStepsError if steps.empty?
-
-        steps.values
+        steps.any? ? steps.values : raise(EmptyStepsError)
       end
 
       # Retrieves a Step object from the builder's steps based on the step name.
       #
       # @param name [String] The name of the step to be converted to a Step object.
       # @return [Step] The corresponding Step object.
-      # @raise [InvalidStepError] Raises if the specified step name is not present in the steps hash.
+      # @raise [StepError] Raises if the specified step name is not present in the steps hash.
       def convert_to_step!(name)
-        steps[name] || raise(InvalidStepError.new(name, steps.keys))
+        steps[name] || raise(StepError.new(name, steps.keys))
+      end
+
+      # Raises an UndefinedMethodError indicating that the conversion method is not defined for the class.
+      #
+      # @param klass [Class] The class that does not have the conversion method defined.
+      # @raise [UndefinedMethodError] Raises an error indicating the missing conversion method.
+      def undefined_method_error!(klass)
+        raise UndefinedMethodError.new(klass, Step::CONVERSION_METHOD)
       end
     end
   end

data/lib/onboardable/list/navigation.rb

@@ -8,30 +8,48 @@ module Onboardable
       #
       # @return [Step, nil] The next step in the list or nil if the current step is the last one.
       def next_step
-        current_index = step_index!(current_step)
+        current_index = step_index(current_step)
         steps[current_index.next]
       end
 
+      # Checks if the specified step is the next step in the onboarding process.
+      #
+      # @param step [Step] The step to check.
+      # @return [Boolean] True if the specified step is the next step, false otherwise.
+      def next_step?(step)
+        next_step == step
+      end
+
       # Moves the current step pointer to the next step in the onboarding process.
       #
-      # @raise [LastStepError] if the current step is the last step and there is no next step to move to.
+      # @return [Step] The next step in the list.
+      # @raise [LastStepError] If the current step is the last step and there is no next step to move to.
       def next_step!
-        self.current_step = next_step || raise(LastStepError.new(current_step, steps.map(&:to_str)))
+        self.current_step = next_step || last_step_error!
       end
 
       # Returns the previous step in the onboarding process.
       #
       # @return [Step, nil] The previous step in the list or nil if the current step is the first one.
       def prev_step
-        current_index = step_index!(current_step)
+        current_index = step_index(current_step)
         current_index.positive? ? steps[current_index.pred] : nil
       end
 
+      # Checks if the specified step is the previous step in the onboarding process.
+      #
+      # @param step [Step] The step to check.
+      # @return [Boolean] True if the specified step is the previous step, false otherwise.
+      def prev_step?(step)
+        prev_step == step
+      end
+
       # Moves the current step pointer to the previous step in the onboarding process.
       #
-      # @raise [FirstStepError] if the current step is the first step and there is no previous step to move to.
+      # @return [Step] The previous step in the list.
+      # @raise [FirstStepError] If the current step is the first step and there is no previous step to move to.
       def prev_step!
-        self.current_step = prev_step || raise(FirstStepError.new(current_step, steps.map(&:to_str)))
+        self.current_step = prev_step || first_step_error!
       end
 
       # Checks if the specified step is the first step in the onboarding process.
@@ -39,7 +57,7 @@ module Onboardable
       # @param step [Step] The step to check (defaults to the current step if not specified).
       # @return [Boolean] True if the specified step is the first step, false otherwise.
       def first_step?(step = current_step)
-        step == first_step
+        first_step == step
       end
 
       # Checks if the specified step is the last step in the onboarding process.
@@ -47,7 +65,7 @@ module Onboardable
       # @param step [Step] The step to check (defaults to the current step if not specified).
       # @return [Boolean] True if the specified step is the last step, false otherwise.
       def last_step?(step = current_step)
-        step == last_step
+        last_step == step
       end
 
       # Retrieves the first step in the onboarding process.
@@ -57,12 +75,36 @@ module Onboardable
         steps.fetch(0)
       end
 
+      # Checks if the specified step is the current step in the onboarding process.
+      #
+      # @param step [Step] The step to check.
+      # @return [Boolean] True if the specified step is the current step, false otherwise.
+      def current_step?(step)
+        current_step == step
+      end
+
       # Retrieves the last step in the onboarding process.
       #
       # @return [Step] The last step in the list.
       def last_step
         steps.fetch(-1)
       end
+
+      private
+
+      # Raises a FirstStepError indicating the current step is the first step in the onboarding process.
+      #
+      # @raise [FirstStepError] The error indicating the current step is the first step.
+      def first_step_error!
+        raise FirstStepError.new(current_step, steps.map(&:to_str))
+      end
+
+      # Raises a LastStepError indicating the current step is the last step in the onboarding process.
+      #
+      # @raise [LastStepError] The error indicating the current step is the last step.
+      def last_step_error!
+        raise LastStepError.new(current_step, steps.map(&:to_str))
+      end
     end
   end
 end

data/lib/onboardable/step.rb

@@ -70,15 +70,14 @@ module Onboardable
     # 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
     def update_status!(comparison_result)
       self.status = case comparison_result
                     when -1 then COMPLETED_STATUS
                     when 0 then CURRENT_STATUS
                     when 1 then PENDING_STATUS
-                    else
-                      raise ComparisonResultError.new(comparison_result, [-1, 0, 1])
-                    end
+                    else comparison_result_error!(comparison_result); end
     end
 
     private
@@ -90,6 +89,15 @@ module Onboardable
       @name = String.new(String.try_convert(raw_name)).freeze
     end
 
+    # Sets the 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))
+
+      @status = raw_status
+    end
+
     # Sets the custom data for the step, ensuring it is a valid Hash.
     #
     # @param raw_data [Hash] the raw custom data
@@ -97,9 +105,12 @@ module Onboardable
       @data = Hash(Hash.try_convert(raw_data)).freeze
     end
 
-    # Sets the status of the step.
+    # Raises an error for an invalid comparison result.
     #
-    # @param status [Symbol] the new status of the step
-    attr_writer :status
+    # @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
   end
 end

data/lib/onboardable/utils/warnings.rb

@@ -9,7 +9,7 @@ module Onboardable
       # Issues a warning when a step with the same name already exists and will be overridden.
       #
       # @param name [String] The name of the step that will be overridden.
-      # @return [void]
+      # @return [void] Returns nothing.
       def warn_about_override(name)
         warn "Step `#{name}` already exists and will be overridden.", uplevel: 1
       end

data/lib/onboardable/version.rb

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

data/lib/onboardable.rb

@@ -12,7 +12,8 @@ require_relative 'onboardable/version'
 module Onboardable
   # Initializes the Onboardable module when included in a class, extending it with class and instance methods.
   #
-  # @param klass [Class] the class including the Onboardable module
+  # @param klass [Module] the class including the Onboardable module
+  # @return [untyped]
   def self.included(klass)
     klass.extend ClassMethods
     klass.include InstanceMethods
@@ -30,20 +31,29 @@ module Onboardable
     # Configures onboarding steps via a ListBuilder with a provided block.
     #
     # @yield [List::Builder] executes block in the context of List::Builder
+    # @return [Step] the current step in the building process
     def list_builder=(&block)
       list_builder.instance_eval(&block)
     end
     alias has_onboarding list_builder=
+
+    # Builds the onboarding list and optionally sets the current step.
+    #
+    # @param current_step_name [String, nil] the name of the current step, if specified
+    # @return [List::Base] the List built from the class's ListBuilder
+    def onboarding(current_step_name = nil)
+      list_builder.build!(current_step_name)
+    end
   end
 
   # Instance methods for onboarding navigation, added to classes including Onboardable.
   module InstanceMethods
-    # Builds a List from the ListBuilder at the class level, optionally specifying the current step.
+    # Builds the onboarding list and optionally sets the current step.
     #
     # @param current_step_name [String, nil] the name of the current step, if specified
     # @return [List::Base] the List built from the class's ListBuilder
     def onboarding(current_step_name = nil)
-      self.class.list_builder.build!(current_step_name)
+      self.class.onboarding(current_step_name)
     end
   end
 end

data/sig/onboardable/errors.rbs

@@ -14,7 +14,7 @@ module Onboardable
     def initialize: () -> void
   end
 
-  class InvalidStepError < Error
+  class StepError < Error
     def initialize: (String, Array[String]) -> void
   end
 
@@ -29,4 +29,8 @@ module Onboardable
   class FirstStepError < Error
     def initialize: (String, Array[String]) -> void
   end
+
+  class StepStatusError < Error
+    def initialize: (Symbol, Array[Symbol]) -> void
+  end
 end

data/sig/onboardable/list/base.rbs

@@ -13,7 +13,11 @@ module Onboardable
       attr_writer steps: Array[Step]
       attr_writer current_step: Step
 
-      def step_index!: (Step)-> Integer
+      def step_error!: (Step) -> void
+
+      def step_index: (Step)-> Integer
+
+      def update_each_step_status: (Integer) -> Array[Step]
     end
   end
 end

data/sig/onboardable/list/builder.rbs

@@ -23,6 +23,8 @@ module Onboardable
       def convert_to_step!: (String) -> Step
 
       def convert_to_steps!: -> Array[Step]
+
+      def undefined_method_error!: (Class) -> void
     end
   end
 end

data/sig/onboardable/list/navigation.rbs

@@ -3,12 +3,24 @@ module Onboardable
     module Navigation
       def next_step: () -> Step?
       def next_step!: () -> Step
+      def next_step?: (Step) -> bool
+
       def prev_step: () -> Step?
+      def prev_step?: (Step) -> bool
       def prev_step!: () -> Step
-      def first_step?: (?Step) -> bool
+
       def first_step: -> Step
-      def last_step?: (?Step) -> bool
+      def first_step?: (?Step) -> bool
+
       def last_step: -> Step
+      def last_step?: (?Step) -> bool
+
+      def current_step?: (Step) -> bool
+
+      private
+
+      def first_step_error!: -> void
+      def last_step_error!: -> void
     end
   end
 end

data/sig/onboardable/step.rbs

@@ -28,5 +28,7 @@ module Onboardable
     attr_writer name: String
     attr_writer data: Hash[Symbol, untyped]
     attr_writer status: Symbol
+
+    def comparison_result_error!: (Integer) -> void
   end
 end

data/sig/onboardable.rbs

@@ -7,9 +7,11 @@ module Onboardable
 
     def list_builder=: () { () -> List::Builder } -> Step
     alias has_onboarding list_builder=
+
+    def onboarding: (String?) -> List::Base
   end
 
   module InstanceMethods
-    def onboarding: (String?) -> List
+    def onboarding: (String?) -> List::Base
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: onboardable
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Artem Skrynnyk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -50,20 +50,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.63'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.63.5
+        version: '1.64'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.63'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.63.5
+        version: '1.64'
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
@@ -164,7 +158,7 @@ metadata:
   homepage_uri: https://github.com/dmrAnderson/onboardable
   changelog_uri: https://github.com/dmrAnderson/onboardable/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/dmrAnderson/onboardable/issues
-  documentation_uri: https://github.com/dmrAnderson/onboardable/blob/main/README.md
+  documentation_uri: https://rubydoc.info/gems/onboardable
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []