onboardable 1.0.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cc331c83492d5c21563a91644b3f2441b38d561ebde4d0690ba68813fadeb60
-  data.tar.gz: 1e55f9c4913a17385c6e2ebe4c7d1dd58921a35b72d786171aa8a28efae09306
+  metadata.gz: ef1662a800c2b2c562af504026f4a84bd7a93c895236784e20e53659d7fdcaa3
+  data.tar.gz: 90df600da2944d056ca6d64891a311e4507f1227c2827b44485735451ccc329d
 SHA512:
-  metadata.gz: '0456826a6d0b6bea084f95191240ea28776be3b4d8106a2f8055b259d24524055248143e01050be87e6c512084e9ddf7c576c594327ae9b617eb1db5e7068973'
-  data.tar.gz: 2e35337681b26a2c09fa7ba1e7e8b5c505747a5c0144f3116214241c06aca3b04d76b72ce439d14ca717090caa01e95f7f219543784dcdbc07b354b66984686f
+  metadata.gz: 32e156cde48492f62a29a41b1c382c1be86bd5922b47ddcd32a5ca606127204002f8805da9c1adc087ea005c90a26a20de9081939617d9f623f9b5075fecd113
+  data.tar.gz: 3f8a70a79552741d71c0de140204220e66d70b5a43e5e7ce3c54c15b06900e55e15f5c840812c3463f3c10909bb693788e0aeaeb8039617a026b2fe2cef2bcc0

data/.rubocop.yml

@@ -7,8 +7,5 @@ AllCops:
   NewCops: enable
   TargetRubyVersion: 3.0.0
 
-Style/Documentation:
-  Enabled: false
-
 Gemspec/DevelopmentDependencies:
   EnforcedStyle: gemspec

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+- 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.
+- Added warn_about_override method to alert on step overrides.
+- Added YARD documentation to the project for improved code documentation.
+
+## [1.0.1] - 2024-05-09
+
 - Added `first_step` and `last_step` methods to easily access
   the boundaries of step lists.
 - Added `progress` method for calculating onboarding completion percentage.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    onboardable (1.0.1)
+    onboardable (1.1.1)
 
 GEM
   remote: https://rubygems.org/
@@ -15,11 +15,12 @@ GEM
     parser (3.3.1.0)
       ast (~> 2.4.1)
       racc
-    racc (1.7.3)
+    racc (1.8.0)
     rainbow (3.1.1)
     rake (13.2.1)
-    regexp_parser (2.9.0)
-    rexml (3.2.6)
+    regexp_parser (2.9.2)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -33,7 +34,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
-    rubocop (1.63.4)
+    rubocop (1.63.5)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
@@ -69,6 +70,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.12.3)
     simplecov_json_formatter (0.1.4)
+    strscan (3.1.0)
     unicode-display_width (2.5.0)
 
 PLATFORMS
@@ -79,7 +81,7 @@ DEPENDENCIES
   onboardable!
   rake (~> 13.2, >= 13.2.1)
   rspec (~> 3.13)
-  rubocop (~> 1.63, >= 1.63.4)
+  rubocop (~> 1.63, >= 1.63.5)
   rubocop-performance (~> 1.21)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.29, >= 2.29.2)

data/README.md

@@ -31,32 +31,31 @@ project as per the installation guide provided earlier.
 
 ### Basic Configuration
 
-1. **Include Onboardable in Your Class**
-
-   Decide which Ruby class should have the onboarding process.
-   For example, if you want to add an onboarding process to a `User`
-   class, you would modify the class as follows:
+   To incorporate an onboarding process into your Ruby User class, start by
+   including the Onboardable module to add onboarding functionality. Then,
+   define the onboarding steps with the has_onboarding method, detailing each
+   step with helpful tooltips and descriptions. Here's how you can set it up:
 
    ```ruby
    class User
      include Onboardable
-   end
-   ```
 
-1. **Define Onboarding Steps**
+     has_onboarding do
+       # Use the `step` method to steps with a name and optional data
+       step 'welcome', message: 'Welcome to your new account!'
+       step 'account_setup', task: 'Create credentials'
+       step 'confirmation'
 
-   You can define the steps involved in the onboarding process using
-   the `has_onboarding` method provided by the gem. Here's an example of
-   how to define a simple onboarding process with custom steps,
-   potentially including specific data for each step:
+       # Use the `step_from` method to define steps from external providers
+       step_from ExternalStepProvider
+     end
+   end
 
-   ```ruby
-   class User
-     has_onboarding do
-       step 'Create Account', tooltip: 'Minimum 8 characters.'
-       step('Verify Email', Class.new { def self.to_hash = { required: true } })
-       step 'Complete Profile' # This step does not include specific action data
-       step 'Introduction Tour', description: 'Get to know your new workspace!'
+   # External class for providing a reusable onboarding step
+   class ExternalStepProvider
+     # Define class method to return an onboarding step
+     def self.to_onboarding_step
+       Onboardable::Step.new('external_step', info: 'This is an external step.')
      end
    end
    ```
@@ -79,7 +78,6 @@ that allow step navigation and state verification:
 
    ```ruby
    onboarding = User.new.onboarding
-   # Initializes the onboarding process for a new user instance
    ```
 
 1. **Navigating Through Steps**
@@ -93,11 +91,8 @@ that allow step navigation and state verification:
       what's next or advance to it, updating the current step status.
 
       ```ruby
-      onboarding.next_step
-      # Returns the next step without changing the current step
-
-      onboarding.next_step!
-      # Advances to the next step, updating the current step
+      onboarding.next_step  # Preview the next step
+      onboarding.next_step! # Advance to the next step
       ```
 
    - **Previous Step**
@@ -106,11 +101,8 @@ that allow step navigation and state verification:
      making changes or updates to revert to the previous step.
 
      ```ruby
-     onboarding.prev_step
-     # Returns the previous step without changing the current step
-
-     onboarding.prev_step!
-     # Reverts to the previous step, updating the current step
+     onboarding.prev_step  # Preview the previous step
+     onboarding.prev_step! # Move back to the previous step
      ```
 
 1. **Check Step Position**
@@ -119,11 +111,8 @@ that allow step navigation and state verification:
    to manage UI elements like 'Next' or 'Back' buttons appropriately.
 
    ```ruby
-   onboarding.first_step?
-   # Returns true if the current step is the first
-
-   onboarding.last_step?
-   # Returns true if the current step is the last
+   onboarding.first_step? # Is the first step?
+   onboarding.last_step?  # Is the last step?
    ```
 
 1. **Monitor Progress**
@@ -132,8 +121,7 @@ that allow step navigation and state verification:
    to provide users with an indication of how far they have progressed.
 
    ```ruby
-   onboarding.progress
-   # Returns the percentage of onboarding completion
+   onboarding.progress # Returns the completion percentage
    ```
 
 1. **Access Current Step Details**
@@ -143,17 +131,10 @@ that allow step navigation and state verification:
    the user complete tasks associated with the step.
 
    ```ruby
-   onboarding.current_step
-   # Returns the current step in the onboarding process
-
-   onboarding.current_step.name
-   # Returns the name of the current step
-
-   onboarding.current_step.data
-   # Returns the custom data associated with the step or an empty hash if not specified
-
-   onboarding.current_step.status
-   # Provides the current status or progress of the step
+   onboarding.current_step        # Current step details
+   onboarding.current_step.name   # Step name
+   onboarding.current_step.data   # Step custom data
+   onboarding.current_step.status # Step status
    ```
 
 1. **Complete the Onboarding Process**

data/lib/onboardable/errors.rb

@@ -1,33 +1,79 @@
 # frozen_string_literal: true
 
 module Onboardable
+  # Base error class for Onboardable-related exceptions.
   class Error < StandardError; end
 
-  class EmptyListError < Error
+  # Error raised when a method is called on an object that does not define it.
+  class UndefinedMethodError < Error
+    # Initializes a new instance of UndefinedMethodError.
+    #
+    # @param klass [Class] The class that does not have the method defined.
+    # @param method [Symbol, String] The name of the method that is not defined.
+    def initialize(klass, method)
+      super("Method `#{method}` is not defined for `#{klass}`.")
+    end
+  end
+
+  # Error raised when an object cannot be converted to a Step.
+  class StepConversionError < Error
+    # Initializes a new instance of StepConversionError.
+    #
+    # @param klass [Class] The class that failed to convert.
+    # @param step [Object] The object returned by the failed conversion.
+    def initialize(klass, step)
+      super("can't convert #{klass} to Step (#{klass}#to_onboarding_step gives #{step.class}).")
+    end
+  end
+
+  # Error raised when an operation is attempted on an empty steps collection.
+  class EmptyStepsError < Error
+    # Initializes a new instance of EmptyStepsError.
+    # This error indicates that an operation requiring non-empty steps was attempted on an empty collection.
     def initialize
-      super('Cannot be performed because the list is empty.')
+      super('Cannot be performed because the steps is empty.')
     end
   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.
+    #
+    # @param step [String] The invalid step that triggered the error.
+    # @param expected_steps [Array<String>] The list of valid steps expected at this point.
     def initialize(step, expected_steps)
       super("Invalid step: `#{step}`. Must be one of: `#{expected_steps.join('`, `')}`.")
     end
   end
 
-  class InvalidComparisonResultError < Error
+  # Error raised when an invalid comparison result is encountered.
+  class ComparisonResultError < Error
+    # Initializes a new ComparisonResultError with details about the issue.
+    #
+    # @param comparison [Integer] The invalid comparison result that triggered the error.
+    # @param expected_comparisons [Array<Integer>] The list of valid comparison results expected.
     def initialize(comparison, expected_comparisons)
       super("Invalid comparison result: `#{comparison}`. Must be one of: #{expected_comparisons.join('`, `')}.")
     end
   end
 
+  # Error raised when attempting to navigate beyond the last step in the onboarding process.
   class LastStepError < Error
+    # Initializes a new LastStepError indicating that the end of the step sequence has been reached.
+    #
+    # @param step [String] The last step that was attempted to be surpassed.
+    # @param expected_steps [Array<String>] The complete list of valid steps in the onboarding process.
     def initialize(step, expected_steps)
       super("Currently `#{step}` the last step. Available steps are: `#{expected_steps.join('`, `')}`.")
     end
   end
 
+  # Error raised when attempting to navigate before the first step in the onboarding process.
   class FirstStepError < Error
+    # Initializes a new FirstStepError indicating that the beginning of the step sequence has been reached.
+    #
+    # @param step [String] The first step that was attempted to be preceded.
+    # @param expected_steps [Array<String>] The complete list of valid steps in the onboarding process.
     def initialize(step, expected_steps)
       super("Currently `#{step}` the first step. Available steps are: `#{expected_steps.join('`, `')}`.")
     end

data/lib/onboardable/list/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Onboardable
+  module List
+    # The List class manages a sequence of steps in an onboarding process, tracking progress and current state.
+    class Base
+      include Navigation
+
+      # @return [Array<Step>] the steps in the list
+      attr_reader :steps
+
+      # @return [Step] the current step in the list
+      attr_reader :current_step
+
+      # Initializes a new instance of List with steps and a current step.
+      #
+      # @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)
+        self.steps = steps
+        self.current_step = current_step
+      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
+      end
+
+      private
+
+      # 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.
+      def steps=(steps)
+        @steps = Array(Array.try_convert(steps)).freeze
+      end
+
+      # 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.
+      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)
+      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)))
+      end
+    end
+  end
+end

data/lib/onboardable/list/builder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Onboardable
+  module List
+    # The Builder class constructs and manages an onboarding step list, adding steps and building the final list.
+    class Builder
+      include Utils::Warnings
+
+      # @return [Hash] A hash where keys are step names and values are Step objects.
+      attr_reader :steps
+
+      # @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 = {}
+      end
+
+      # Creates a new Step object and adds it to the builder.
+      #
+      # @param name [String] The name of the step.
+      # @param data [Hash] The data associated with the step.
+      # @return [Step] The created step.
+      def create_step(name, data = {})
+        Step.new(name, data).tap { |step| add_step(step) }
+      end
+      alias step create_step
+
+      # 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.
+      def create_step_from!(klass)
+        Step.try_convert(klass).tap do |step|
+          add_step(step || raise(UndefinedMethodError.new(klass, Step::CONVERSION_METHOD)))
+        end
+      end
+      alias step_from create_step_from!
+
+      # Constructs a new List object from the steps added to the builder.
+      #
+      # @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.
+      def build!(current_step_name)
+        Base.new(convert_to_steps!, convert_to_step!(current_step_name || current_step.name))
+      end
+
+      private
+
+      # Adds a step to the builder.
+      #
+      # @param step [Step] The step to be added.
+      def add_step(step)
+        step.name.then do |name|
+          warn_about_override(name) if steps.key?(name)
+          steps[name] = step
+        end
+
+        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.
+      # @raise [EmptyStepsError] Raises if there are no steps to convert.
+      def convert_to_steps!
+        raise EmptyStepsError if steps.empty?
+
+        steps.values
+      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.
+      def convert_to_step!(name)
+        steps[name] || raise(InvalidStepError.new(name, steps.keys))
+      end
+    end
+  end
+end

data/lib/onboardable/list/navigation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Onboardable
+  module List
+    # The Navigation module provides methods for navigating through the steps of the onboarding process.
+    module Navigation
+      # Returns the next step in the onboarding process.
+      #
+      # @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)
+        steps[current_index.next]
+      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.
+      def next_step!
+        self.current_step = next_step || raise(LastStepError.new(current_step, steps.map(&:to_str)))
+      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.positive? ? steps[current_index.pred] : nil
+      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.
+      def prev_step!
+        self.current_step = prev_step || raise(FirstStepError.new(current_step, steps.map(&:to_str)))
+      end
+
+      # Checks if the specified step is the first step in the onboarding process.
+      #
+      # @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
+      end
+
+      # Checks if the specified step is the last step in the onboarding process.
+      #
+      # @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
+      end
+
+      # Retrieves the first step in the onboarding process.
+      #
+      # @return [Step] The first step in the list.
+      def first_step
+        steps.fetch(0)
+      end
+
+      # Retrieves the last step in the onboarding process.
+      #
+      # @return [Step] The last step in the list.
+      def last_step
+        steps.fetch(-1)
+      end
+    end
+  end
+end

data/lib/onboardable/step.rb

@@ -1,56 +1,105 @@
 # frozen_string_literal: true
 
 module Onboardable
+  # Represents a single step within an onboarding process, including its status and associated data.
   class Step
+    CONVERSION_METHOD = :to_onboarding_step
+
     PENDING_STATUS = :pending
     CURRENT_STATUS = :current
     COMPLETED_STATUS = :completed
+
     DEFAULT_STATUS = PENDING_STATUS
+
     STATUSES = [PENDING_STATUS, CURRENT_STATUS, COMPLETED_STATUS].freeze
 
-    attr_reader :name, :data, :status
+    class << self
+      def try_convert(value)
+        return unless value.respond_to?(CONVERSION_METHOD)
+
+        value.public_send(CONVERSION_METHOD).then do |step|
+          step.is_a?(Step) ? step : raise(StepConversionError.new(value, step))
+        end
+      end
+    end
+
+    # @return [String] the name of the step
+    attr_reader :name
+
+    # @return [Hash] custom data associated with the step
+    attr_reader :data
 
+    # @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
     def initialize(name, data = {})
       self.name = name
       self.data = data
-
       self.status = DEFAULT_STATUS
     end
 
     STATUSES.each do |status_method|
+      # @!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.
       define_method :"#{status_method}?" do
         status == status_method
       end
     end
 
+    # 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
     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
     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)
+    # @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 InvalidComparisonResultError.new(comparison_result, [-1, 0, 1])
+                      raise ComparisonResultError.new(comparison_result, [-1, 0, 1])
                     end
     end
 
     private
 
+    # Sets the name of the step, ensuring it is a valid String.
+    #
+    # @param raw_name [String] the raw name of the step
     def name=(raw_name)
       @name = String.new(String.try_convert(raw_name)).freeze
     end
 
+    # Sets the custom data for the step, ensuring it is a valid Hash.
+    #
+    # @param raw_data [Hash] the raw custom data
     def data=(raw_data)
       @data = Hash(Hash.try_convert(raw_data)).freeze
     end
 
+    # Sets the status of the step.
+    #
+    # @param status [Symbol] the new status of the step
     attr_writer :status
   end
 end

data/lib/onboardable/utils/warnings.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Onboardable
+  module Utils
+    # The Warnings module provides utility methods for issuing warnings.
+    module Warnings
+      private
+
+      # 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]
+      def warn_about_override(name)
+        warn "Step `#{name}` already exists and will be overridden.", uplevel: 1
+      end
+    end
+  end
+end

data/lib/onboardable/version.rb

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

data/lib/onboardable.rb

@@ -1,32 +1,59 @@
 # frozen_string_literal: true
 
-require_relative 'onboardable/utils/navigation'
 require_relative 'onboardable/errors'
-require_relative 'onboardable/list'
-require_relative 'onboardable/list_builder'
+require_relative 'onboardable/utils/warnings'
+require_relative 'onboardable/list/navigation'
+require_relative 'onboardable/list/builder'
+require_relative 'onboardable/list/base'
 require_relative 'onboardable/step'
 require_relative 'onboardable/version'
 
+# The Onboardable module provides a DSL for defining and navigating onboarding steps.
 module Onboardable
+  # Initializes the Onboardable module when included in a class, extending it with class and instance methods.
+  #
+  # @param klass [Module] the class including the Onboardable module
+  # @return [untyped]
   def self.included(klass)
     klass.extend ClassMethods
     klass.include InstanceMethods
   end
 
+  # 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 ||= ListBuilder.new
+      @list_builder ||= List::Builder.new
     end
 
+    # 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 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

@@ -0,0 +1,32 @@
+module Onboardable
+  class Error < StandardError
+  end
+
+  class UndefinedMethodError < Error
+    def initialize: (Class, Symbol | String) -> void
+  end
+
+  class StepConversionError < Error
+    def initialize: (Class, untyped) -> void
+  end
+
+  class EmptyStepsError < Error
+    def initialize: () -> void
+  end
+
+  class InvalidStepError < Error
+    def initialize: (String, Array[String]) -> void
+  end
+
+  class ComparisonResultError < Error
+    def initialize: (Integer, Array[Integer]) -> void
+  end
+
+  class LastStepError < Error
+    def initialize: (String, Array[String]) -> void
+  end
+
+  class FirstStepError < Error
+    def initialize: (String, Array[String]) -> void
+  end
+end

data/sig/onboardable/list/base.rbs

@@ -0,0 +1,19 @@
+module Onboardable
+  module List
+    class Base
+      attr_reader steps: Array[Step]
+      attr_reader current_step: Step
+
+      def initialize: (Array[Step], Step) -> instance
+
+      def progress: -> Float
+
+      private
+
+      attr_writer steps: Array[Step]
+      attr_writer current_step: Step
+
+      def step_index!: (Step)-> Integer
+    end
+  end
+end

data/sig/onboardable/list/builder.rbs

@@ -0,0 +1,28 @@
+module Onboardable
+  module List
+    class Builder
+      attr_reader steps: Hash[String, Step]
+      attr_accessor current_step: Step
+
+      def initialize: () -> Hash[String, Step]
+
+      def create_step: (String, Hash[Symbol, untyped]) -> Step
+      alias step create_step
+
+      def create_step_from!: (Class) -> Step
+      alias step_from create_step_from!
+
+      def build!: (String?) -> Base
+
+      private
+
+      attr_writer steps: Hash[String, Step]
+
+      def add_step: (Step) -> Step
+
+      def convert_to_step!: (String) -> Step
+
+      def convert_to_steps!: -> Array[Step]
+    end
+  end
+end

data/sig/onboardable/{utils → list}/navigation.rbs

@@ -1,5 +1,5 @@
 module Onboardable
-  module Utils
+  module List
     module Navigation
       def next_step: () -> Step?
       def next_step!: () -> Step

data/sig/onboardable/step.rbs

@@ -1,11 +1,14 @@
 module Onboardable
   class Step
+    CONVERSION_METHOD: Symbol
     PENDING_STATUS: Symbol
     CURRENT_STATUS: Symbol
     COMPLETED_STATUS: Symbol
     DEFAULT_STATUS: Symbol
     STATUSES: Array[Symbol]
 
+    def self.try_convert: -> Step?
+
     attr_reader name: String
     attr_reader data: Hash[Symbol, untyped]
     attr_reader status: Symbol

data/sig/onboardable/utils/warnings.rbs

@@ -0,0 +1,9 @@
+module Onboardable
+  module Utils
+    module Warnings
+      private
+
+      def warn_about_override: (Hash[String, Step]) -> void
+    end
+  end
+end

data/sig/onboardable.rbs

@@ -3,13 +3,15 @@ module Onboardable
   # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 
   module ClassMethods
-    attr_reader list_builder: ListBuilder
+    attr_reader list_builder: List::Builder
 
-    def list_builder=: () { () -> ListBuilder } -> Step
+    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.0.1
+  version: 1.1.1
 platform: ruby
 authors:
 - Artem Skrynnyk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-09 00:00:00.000000000 Z
+date: 2024-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -53,7 +53,7 @@ dependencies:
         version: '1.63'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.63.4
+        version: 1.63.5
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -63,7 +63,7 @@ dependencies:
         version: '1.63'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.63.4
+        version: 1.63.5
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
@@ -144,16 +144,19 @@ files:
 - Rakefile
 - lib/onboardable.rb
 - lib/onboardable/errors.rb
-- lib/onboardable/list.rb
-- lib/onboardable/list_builder.rb
+- lib/onboardable/list/base.rb
+- lib/onboardable/list/builder.rb
+- lib/onboardable/list/navigation.rb
 - lib/onboardable/step.rb
-- lib/onboardable/utils/navigation.rb
+- lib/onboardable/utils/warnings.rb
 - lib/onboardable/version.rb
 - sig/onboardable.rbs
-- sig/onboardable/list.rbs
-- sig/onboardable/list_builder.rbs
+- sig/onboardable/errors.rbs
+- sig/onboardable/list/base.rbs
+- sig/onboardable/list/builder.rbs
+- sig/onboardable/list/navigation.rbs
 - sig/onboardable/step.rbs
-- sig/onboardable/utils/navigation.rbs
+- sig/onboardable/utils/warnings.rbs
 homepage: https://github.com/dmrAnderson/onboardable
 licenses:
 - MIT
@@ -161,7 +164,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: []

data/lib/onboardable/list.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-module Onboardable
-  class List
-    include Utils::Navigation
-
-    attr_reader :steps, :current_step
-
-    def initialize(steps, current_step)
-      self.steps = steps
-      self.current_step = current_step
-    end
-
-    def progress
-      (step_index!(current_step).to_f / steps.size) * 100
-    end
-
-    private
-
-    def steps=(raw_steps)
-      Array(Array.try_convert(raw_steps)).then do |converted_steps|
-        raise EmptyListError if converted_steps.empty?
-
-        @steps = converted_steps.freeze
-      end
-    end
-
-    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)
-    end
-
-    def step_index!(raw_step)
-      steps.index { |step| step == raw_step } || raise(InvalidStepError.new(raw_step, steps.map(&:to_str)))
-    end
-  end
-end

data/lib/onboardable/list_builder.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Onboardable
-  class ListBuilder
-    attr_reader :steps
-    attr_accessor :current_step
-
-    def initialize
-      self.steps = {}
-    end
-
-    def add_step(name, data = {})
-      Step.new(name, data).tap do |step|
-        steps[name] = step
-        self.current_step ||= step
-      end
-    end
-    alias step add_step
-
-    def build!(current_step_name)
-      List.new(steps.values, convert_to_step!(current_step_name))
-    end
-
-    private
-
-    def steps=(raw_steps)
-      @steps = Hash(Hash.try_convert(raw_steps))
-    end
-
-    def convert_to_step!(name)
-      return current_step unless name
-
-      steps[name] || raise(InvalidStepError.new(name, steps.keys))
-    end
-  end
-end

data/lib/onboardable/utils/navigation.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Onboardable
-  module Utils
-    module Navigation
-      def next_step
-        current_index = step_index!(current_step)
-
-        steps[current_index.next]
-      end
-
-      def next_step!
-        self.current_step = next_step || raise(LastStepError.new(current_step, steps))
-      end
-
-      def prev_step
-        current_index = step_index!(current_step)
-
-        current_index.positive? ? steps[current_index.pred] : nil
-      end
-
-      def prev_step!
-        self.current_step = prev_step || raise(FirstStepError.new(current_step, steps))
-      end
-
-      def first_step?(step = current_step)
-        step == first_step
-      end
-
-      def last_step?(step = current_step)
-        step == last_step
-      end
-
-      def first_step
-        steps.fetch(0)
-      end
-
-      def last_step
-        steps.fetch(-1)
-      end
-    end
-  end
-end

data/sig/onboardable/list.rbs

@@ -1,17 +0,0 @@
-module Onboardable
-  class List
-    attr_reader steps: Array[Step]
-    attr_reader current_step: Step
-
-    def initialize: (Array[Step], Step) -> instance
-
-    def progress: -> Float
-
-    private
-
-    attr_writer steps: Array[Step]
-    attr_writer current_step: Step
-
-    def step_index!: (Step)-> Integer
-  end
-end

data/sig/onboardable/list_builder.rbs

@@ -1,19 +0,0 @@
-module Onboardable
-  class ListBuilder
-    attr_reader steps: Hash[String, Step]
-    attr_accessor current_step: Step
-
-    def initialize: () -> Hash[String, Step]
-
-    def add_step: (String, Hash[Symbol, untyped]) -> Step
-    alias step add_step
-
-    def build!: (String?) -> List
-
-    private
-
-    attr_writer steps: Hash[String, Step]
-
-    def convert_to_step!: (String?) -> Step
-  end
-end