govuk-wizardry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de9d24e16cac679c4ee2c36dd8a8556dbe051ffabbfc8771c1dcddd5a00964c3
+  data.tar.gz: f7bf947d3cbb3e95b03c12d5f527805c1d005d09a6e12738ae7ec77fc4a644df
+SHA512:
+  metadata.gz: 47ac4127a0b74792a27812c48c5911cea6341a7f215714a6b95003443e8237dc70a9ac85129a8b7e88b9e91e98b276cc18fb5a532ef4fcf5e25ec2419967ffa4
+  data.tar.gz: 98515e090121ce5703f1058190a98ff2d487fa361703bfaefd8578d0c2463621a060ac47b81ba6af566fce3412eac07d4c6ccc62ec0fcc2a03e7f771cef61c07

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2020 Graphia Ltd.
+
+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,107 @@
+# Wizardry 🧙
+
+This gem for Rails allows application writers to define a GOV.UK wizard
+(multi-page form) in one place.
+
+**Note this library is at the very early stages of development. It's not
+properly tested and is very likely to change**.
+
+## Things the library does:
+
+* renders the wizard pages based on the specification ✔
+* correctly annotates the pages using Rails' I18n functionality ✔
+* deals with form submissions ✔
+* applies contextual validation on a per-page basis and displaying error messages ✔
+* let developers override pages and questions with their own partials ✔
+* allow for extra customisation over the size of labels, legends and captions ✔
+* allow conditional logic to customise the path through the journey ✔
+* provide a callbacks upon step and wizard completion ✔
+
+## How does it work?
+
+The wizard relies on the application having a single model that will hold the
+collected data. Each question in the wizard maps to a field and every page
+maps to a [validation context](https://guides.rubyonrails.org/active_record_validations.html#on).
+
+Throughout the process the last completed step is recorded in the model. It's
+used to track progress and hold the state of the response. It is automatically
+updated when a successful submission is made.
+
+### Example
+
+Just include the `Wizardry` module in your controller and use the `wizard` macro
+to define your pages and questions:
+
+```ruby
+class RatingsController < ApplicationController
+  include Wizardry
+
+  wizard name: 'ratings',
+    class_name: 'Rating',
+    edit_path_helper: :ratings_page_path,
+    update_path_helper: :ratings_path,
+    pages: [
+      Wizardry::Pages::Page.new(
+        :identification,
+        title: 'Who are you?',
+        questions: [
+          Wizardry::Questions::ShortAnswer.new(:full_name),
+          Wizardry::Questions::EmailAddress.new(:email)
+        ]
+      ),
+      Wizardry::Pages::Page.new(
+        :feedback,
+        title: 'What did you think about our service?',
+        questions: [
+          Wizardry::Questions::ShortAnswer.new(:customer_type),
+          Wizardry::Questions::Date.new(:purchase_date),
+          Wizardry::Questions::LongAnswer.new(:feedback),
+          Wizardry::Questions::Radios.new(:rating, {
+            1 => 'Dire', 2 => 'Alright', 3 => 'Average', 4 => 'Decent', 5 => 'Amazing'
+          })
+        ]
+      ),
+      Wizardry::Pages::CheckYourAnswersPage.new,
+    ]
+end
+```
+
+### Routes
+
+In the example above, we're providing the `edit_path_helper` and
+`update_path_helper` values. These are the Rails path helpers that correspond
+with the path that displays the current page of the wizard and the path that
+updates the object.
+
+```ruby
+Rails.application.routes.draw do
+  get %(rating/:page), to: %(ratings#edit), as: :ratings_page
+  patch %(rating/:page), to: %(ratings#update), as: :ratings
+end
+```
+
+### Rendering
+
+To add the wizard content to your `edit` template, the gem comes with a
+`wizardry_content` helper. Additionally, the wizard object is available for the
+developer to interact with in the `@wizard` instance variable. Here we are
+using it to set the heading.
+
+```erb
+<h1 class="govuk-heading-l"><%= @wizard.current_page.name.capitalize %></h1>
+
+<%= wizardry_content %>
+```
+
+### Special pages
+
+Most pages in a wizard are ones that ask questions. Many wizards also contain a
+[check your answers](https://design-system.service.gov.uk/patterns/check-answers/) page and
+a page that's displayed upon completion. These are both **in scope** for this
+gem.
+
+### Preview
+
+| Page one | Page two |
+| -----------------| ---------- |
+| ![identification page](doc/images/identification.png) | ![feedback page](doc/images/feedback.png) |

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Wizardry'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/helpers/wizardry_helper.rb

@@ -0,0 +1,121 @@
+module WizardryHelper
+  def wizardry_content(w)
+    case w.current_page
+    when Wizardry::Pages::QuestionPage
+      render_form(w)
+    when Wizardry::Pages::CheckYourAnswersPage
+      safe_join([render_check_your_answers(w), render_form(w)])
+    when Wizardry::Pages::CompletionPage
+      render_completion(w)
+    end
+  end
+
+private
+
+  def render_form(w)
+    capture do
+      try_partial(w, 'page') do
+        wizard_form(w) do |f|
+          try_partial(w, 'form', locals: { f: f }) do
+            concat(f.govuk_error_summary)
+
+            w.current_page.questions.map do |q|
+              concat(f.send(q.form_method, q.name, *q.extra_args, **q.extra_kwargs))
+            end
+
+            concat(f.govuk_submit)
+          end
+        end
+      end
+    end
+  end
+
+  def render_check_your_answers(w)
+    capture do
+      try_partial(w, 'page') do
+        safe_join(
+          [
+            render(GovukComponent::SummaryListComponent.new) do |summary_list|
+              w.route.each do |page|
+                page.questions.each do |question|
+                  summary_list.row do |sl|
+                    sl.key(text: check_your_answers_key(w.object.class.name, question.name))
+                    sl.value(text: w.object.send(question.name))
+                    sl.action(href: send(w.framework.edit_path_helper, page.name))
+                  end
+                end
+              end
+            end
+          ]
+        )
+      end
+    end
+  end
+
+  def render_completion(w)
+    capture do
+      try_partial(w, 'page') do
+        safe_join(
+          [
+            tag.h1('Completed'),
+
+            tag.p do
+              [
+                'Add a partial called',
+                tag.code(%(_completion.html.erb)),
+                'to override this message'
+              ].join(' ').html_safe
+            end
+          ]
+        )
+      end
+    end
+  end
+
+  def wizard_form(w, turbo_frame_id: 'wizardry-form', &block)
+    turbo_frame_tag(turbo_frame_id) do
+      safe_join(
+        [
+          form_for(
+            w.object,
+            url: send(
+              w.framework.update_path_helper,
+              page: w.current_page.name
+            ),
+            method: :patch,
+            builder: GOVUKDesignSystemFormBuilder::FormBuilder,
+            &block
+          )
+        ]
+      )
+    end
+  end
+
+  def try_partial(w, section, locals: {}, &block)
+    if lookup_context.template_exists?(partial_file_path(w, section))
+      Rails.logger.debug("🧙 Page partial #{partial_file_path(w, section)} found; rendering entire page")
+
+      concat(render(partial: partial_render_path(w, section), locals: locals))
+    else
+      Rails.logger.debug('🧙 No overriding form partial found; automatically building form')
+
+      block.call
+    end
+  end
+
+  def check_your_answers_key(class_name, question_name)
+    I18n.t!("helpers.legend.#{class_name.underscore}.#{question_name}")
+  rescue I18n::MissingTranslationData
+    I18n.t("helpers.label.#{class_name.underscore}.#{question_name}")
+  end
+
+  def partial_file_path(w, suffix)
+    "#{w.framework.name}/_#{w.current_page.name}_#{suffix}"
+  end
+
+  def partial_render_path(w, suffix)
+    "#{w.framework.name}/#{w.current_page.name}_#{suffix}"
+  end
+end
+
+ActiveSupport.on_load(:action_view) { include WizardryHelper }

data/lib/tasks/wizardry_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :wizard do
+#   # Task goes here
+# end

data/lib/wizardry/engine.rb

@@ -0,0 +1,7 @@
+module Wizardry
+  class Engine < ::Rails::Engine
+    isolate_namespace Wizardry
+  end
+end
+
+Dir[Wizardry::Engine.root.join(*%w(app helpers *.rb))].each { |f| require f }

data/lib/wizardry/framework.rb

@@ -0,0 +1,56 @@
+module Wizardry
+  # Framework holds data on how the wizard itself is constructed. It'll
+  # be the same for every instance
+  class Framework
+    attr_accessor :name, :pages, :class_name, :edit_path_helper, :update_path_helper, :completion_flag
+
+    def initialize(name:, pages:, class_name:, edit_path_helper:, update_path_helper:, completion_flag: 'complete')
+      @name               = name
+      @pages              = setup_pages(pages)
+      @class_name         = class_name
+      @edit_path_helper   = edit_path_helper
+      @update_path_helper = update_path_helper
+      @completion_flag    = completion_flag
+
+      page_sense_check
+    end
+
+    def cookie_name
+      %(#{@name}-wizard)
+    end
+
+    def page_names
+      pages.map(&:name)
+    end
+
+    def trunk_pages
+      pages.reject(&:branch?)
+    end
+
+    def branch_pages
+      pages.select(&:branch?)
+    end
+
+    def page(name)
+      pages.detect { |p| p.name == name }
+    end
+
+  private
+
+    def page_sense_check
+      # should have no more than one check your answers page
+      pages.count { |page| page.is_a?(Wizardry::Pages::CheckYourAnswersPage) }.tap do |check_your_answers_pages|
+        Rails.logger.warn("🧙 More than one check your answers page detected") if check_your_answers_pages > 1
+      end
+
+      # should have no more than one completion page
+      pages.count { |page| page.is_a?(Wizardry::Pages::CompletionPage) }.tap do |completion_pages|
+        Rails.logger.warn("🧙 More than one completion page detected") if completion_pages > 1
+      end
+    end
+
+    def setup_pages(pages)
+      pages.map { |page| [page, page.pages.each(&:branch!)].select(&:presence) }.flatten
+    end
+  end
+end

data/lib/wizardry/graph.rb

@@ -0,0 +1,55 @@
+module Wizardry
+  class Graph
+    attr_reader :graph
+
+    def initialize(framework)
+      @framework = framework
+      @graph     = reticulate
+    end
+
+    def to_dot
+      <<~GRAPH
+        digraph name {
+          #{build_edges.flatten.join(';')};
+        }
+      GRAPH
+    end
+
+  private
+
+    def reticulate
+      @framework.pages.each.with_index.with_object({}) do |(current, i), g|
+        g[current.name] = specified_next_pages(current).merge(following_page(current, i))
+      end
+    end
+
+    def build_edges
+      @graph.map do |source, targets|
+        targets.map do |target_page, condition|
+          %(#{source} -> #{target_page}).tap do |edge|
+            if condition.present?
+              formatted_condition = %("#{condition}")
+              edge << %( [label=#{formatted_condition}])
+            end
+          end
+        end
+      end
+    end
+
+    def specified_next_pages(page)
+      page.next_pages.each.with_object({}) do |np, h|
+        h[np.name] = np.label
+      end
+    end
+
+    def following_page(_page, index)
+      next_non_branch_page = @framework.pages[index.next..].detect { |p| !p.branch? }
+
+      if next_non_branch_page.present?
+        { next_non_branch_page.name => nil }
+      else
+        { finish: nil }
+      end
+    end
+  end
+end

data/lib/wizardry/instance.rb

@@ -0,0 +1,74 @@
+module Wizardry
+  # Instance holds data specific to this page/response
+  class Instance
+    attr_accessor :current_page, :object, :framework
+
+    def initialize(current_page:, object:, framework:)
+      @object       = object
+      @framework    = framework
+      @current_page = @framework.pages.detect { |p| p.name == current_page.to_sym }
+
+      raise(ActionController::RoutingError, %(Wizard page #{current_page} not found)) unless @current_page
+    end
+
+    def next_page(page = current_page)
+      next_branch_page(page) || next_trunk_page(page)
+    end
+
+    # find all the pages we've visited on our way to
+    # the current page
+    def route(from = framework.pages.first)
+      @route ||= route!(from)
+    end
+
+    def route!(from = framework.pages.first)
+      page = from
+
+      @route = [].tap do |completed|
+        until page == current_page
+          completed << page
+
+          page = next_page(page)
+        end
+      end
+    end
+
+    def valid_so_far?
+      route.all? { |complete_page| object.valid?(complete_page.name) }
+    end
+
+    # check this wizard hasn't already been completed using the
+    # object's :completion_flag
+    def ensure_not_complete
+      raise Wizardry::AlreadyCompletedError if complete?
+    end
+
+    def complete?
+      object.send(framework.completion_flag)
+    end
+
+  private
+
+    def next_branch_page(page)
+      next_page = page.next_pages.detect do |p|
+        p.condition.blank? || p.condition.call(object)
+      end
+
+      return unless next_page
+
+      framework.page(next_page.name)
+    end
+
+    # if the branch ends continue along the trunk from
+    # where we left off
+    def next_trunk_page(page)
+      page_index = framework.pages.index(page)
+
+      framework.pages.detect.with_index do |p, i|
+        next if p.branch?
+
+        i > page_index
+      end
+    end
+  end
+end

data/lib/wizardry/pages/check_your_answers_page.rb

@@ -0,0 +1,22 @@
+module Wizardry
+  module Pages
+    class CheckYourAnswersPage < Page
+      attr_reader :title, :questions
+
+      def initialize(questions: [], title: 'Check your answers')
+        @title     = title
+        @questions = questions
+
+        super(pages: [])
+      end
+
+      def name
+        :check_your_answers
+      end
+
+      def question_names
+        @questions.map(&:name)
+      end
+    end
+  end
+end

data/lib/wizardry/pages/completion_page.rb

@@ -0,0 +1,21 @@
+module Wizardry
+  module Pages
+    class CompletionPage < Page
+      def name
+        :completion
+      end
+
+      def title
+        ''
+      end
+
+      def questions
+        []
+      end
+
+      def next_pages
+        []
+      end
+    end
+  end
+end

data/lib/wizardry/pages/page.rb

@@ -0,0 +1,51 @@
+module Wizardry
+  module Pages
+    class Page
+      attr_reader :pages
+
+      def initialize(pages: [], before_edit: nil, before_update: nil, after_update: nil)
+        @pages  = pages
+        @branch = false
+
+        # callbacks
+        @before_edit   = before_edit
+        @before_update = before_update
+        @after_update  = after_update
+      end
+
+      def branch!
+        @branch = true
+      end
+
+      def branch?
+        @branch
+      end
+
+      def questions
+        []
+      end
+
+      def next_pages
+        []
+      end
+
+      def before_edit!(object)
+        return unless @before_edit
+
+        @before_edit.call(object)
+      end
+
+      def before_update!(object)
+        return unless @before_update
+
+        @before_update.call(object)
+      end
+
+      def after_update!(object)
+        return unless @after_update
+
+        @after_update.call(object)
+      end
+    end
+  end
+end

data/lib/wizardry/pages/question_page.rb

@@ -0,0 +1,22 @@
+module Wizardry
+  module Pages
+    class QuestionPage < Page
+      attr_accessor :name, :questions, :title, :next_pages
+
+      def initialize(name, questions:, next_pages: {}, pages: [], title: nil, before_edit: nil, before_update: nil, after_update: nil)
+        Rails.logger.debug("🧙 Adding page '#{name}' with #{questions&.size || 'no'} questions")
+
+        @name       = name
+        @title      = title || name.capitalize
+        @questions  = questions
+        @next_pages = next_pages
+
+        super(pages: pages, before_edit: before_edit, before_update: before_update, after_update: after_update)
+      end
+
+      def question_names
+        @questions.map(&:name)
+      end
+    end
+  end
+end

data/lib/wizardry/questions/answer.rb

@@ -0,0 +1,19 @@
+module Wizardry
+  module Questions
+    class Answer
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def extra_args
+        []
+      end
+
+      def extra_kwargs
+        {}
+      end
+    end
+  end
+end

data/lib/wizardry/questions/date.rb

@@ -0,0 +1,15 @@
+module Wizardry
+  module Questions
+    # Ask a date question
+    class Date < Wizardry::Questions::Answer
+      def initialize(name)
+        Rails.logger.debug("🧙 Adding date question '#{name}'")
+        super
+      end
+
+      def form_method
+        :govuk_date_field
+      end
+    end
+  end
+end

data/lib/wizardry/questions/email_address.rb

@@ -0,0 +1,15 @@
+module Wizardry
+  module Questions
+    # Ask a respondant for an email address
+    class EmailAddress < Wizardry::Questions::Answer
+      def initialize(name)
+        Rails.logger.debug("🧙 Adding email address question '#{name}'")
+        super
+      end
+
+      def form_method
+        :govuk_email_field
+      end
+    end
+  end
+end

data/lib/wizardry/questions/hidden.rb

@@ -0,0 +1,22 @@
+module Wizardry
+  module Questions
+    class Hidden < Answer
+      attr_reader :name
+
+      def initialize(name, value)
+        Rails.logger.debug("🧙 Adding hidden field '#{name}'")
+        @value = value
+
+        super(name)
+      end
+
+      def form_method
+        :hidden_field
+      end
+
+      def extra_kwargs
+        { value: @value }
+      end
+    end
+  end
+end

data/lib/wizardry/questions/long_answer.rb

@@ -0,0 +1,15 @@
+module Wizardry
+  module Questions
+    # Ask a question that can be answered with multiple lines of text
+    class LongAnswer < Wizardry::Questions::Answer
+      def initialize(name)
+        Rails.logger.debug("🧙 Adding long question '#{name}'")
+        super
+      end
+
+      def form_method
+        :govuk_text_area
+      end
+    end
+  end
+end

data/lib/wizardry/questions/radios.rb

@@ -0,0 +1,36 @@
+module Wizardry
+  module Questions
+    class Radios < Wizardry::Questions::Answer
+      attr_reader :options
+
+      RadioOption = Struct.new(:value, :label, keyword_init: true)
+
+      def initialize(name, options)
+        Rails.logger.debug("🧙 Adding radios '#{name}' with options #{options}")
+
+        @options = options
+
+        super(name)
+      end
+
+      def form_method
+        :govuk_collection_radio_buttons
+      end
+
+      def extra_args
+        [build_options, :value, :label]
+      end
+
+      def build_options
+        case options
+        when Array
+          options.map { |v| Wizardry::Questions::Radios::RadioOption.new(value: v, label: v) }
+        when Hash
+          options.map { |k, v| Wizardry::Questions::Radios::RadioOption.new(value: k, label: v) }
+        else
+          fail ArgumentError, "Options must be an Hash or Array"
+        end
+      end
+    end
+  end
+end

data/lib/wizardry/questions/short_answer.rb

@@ -0,0 +1,15 @@
+module Wizardry
+  module Questions
+    # Ask a question that can be answered with one line of text
+    class ShortAnswer < Wizardry::Questions::Answer
+      def initialize(name)
+        Rails.logger.debug("🧙 Adding short question '#{name}'")
+        super(name)
+      end
+
+      def form_method
+        :govuk_text_field
+      end
+    end
+  end
+end

data/lib/wizardry/questions/telephone_number.rb

@@ -0,0 +1,15 @@
+module Wizardry
+  module Questions
+    # Ask a respondant for a telephone number
+    class TelephoneNumber < Wizardry::Questions::Answer
+      def initialize(name)
+        Rails.logger.debug("🧙 Adding telephone number question '#{name}'")
+        super
+      end
+
+      def form_method
+        :govuk_phone_field
+      end
+    end
+  end
+end

data/lib/wizardry/railtie.rb

@@ -0,0 +1,4 @@
+module Wizardry
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/wizardry/routing/next_page.rb

@@ -0,0 +1,13 @@
+module Wizardry
+  module Routing
+    class NextPage
+      attr_reader :name, :condition, :label
+
+      def initialize(name, condition = nil, label: nil)
+        @name      = name
+        @condition = condition
+        @label     = label
+      end
+    end
+  end
+end

data/lib/wizardry/version.rb

@@ -0,0 +1,3 @@
+module Wizardry
+  VERSION = '0.1.0'.freeze
+end

data/lib/wizardry.rb

@@ -0,0 +1,115 @@
+require "wizardry/engine"
+require "wizardry/railtie"
+require "wizardry/framework"
+require "wizardry/instance"
+
+require "wizardry/pages/page"
+require "wizardry/pages/question_page"
+require "wizardry/pages/check_your_answers_page"
+require "wizardry/pages/completion_page"
+
+require "wizardry/questions/answer"
+require "wizardry/questions/short_answer"
+require "wizardry/questions/long_answer"
+require "wizardry/questions/radios"
+require "wizardry/questions/telephone_number"
+require "wizardry/questions/email_address"
+require "wizardry/questions/date"
+require "wizardry/questions/hidden"
+
+require "wizardry/routing/next_page"
+
+require "govuk_design_system_formbuilder"
+require "govuk/components"
+
+module Wizardry
+  extend ActiveSupport::Concern
+
+  class AlreadyCompletedError < StandardError; end
+
+  class_methods do
+    def wizard(...)
+      define_method(:wizard) do
+        @framework ||= Wizardry::Framework.new(...)
+      end
+    end
+  end
+
+  included do
+    before_action :setup_wizard, :check_wizard
+
+    def edit
+      Rails.logger.debug("🧙 Running before_edit callback")
+      @wizard.current_page.before_edit!(@wizard.object)
+    end
+
+    def update
+      Rails.logger.debug("🧙 Object valid, saving and moving on")
+      @wizard.object.assign_attributes(object_params.merge(last_completed_step_params))
+
+      Rails.logger.debug("🧙 Running before_update callback")
+      @wizard.current_page.before_update!(@wizard.object)
+
+      if @wizard.object.valid?(@wizard.current_page.name)
+        @wizard.object.transaction do
+          @wizard.object.save!
+          Rails.logger.debug("🧙 Object saved, trying after_update callback")
+
+          @wizard.current_page.after_update!(@wizard.object)
+          Rails.logger.debug("🧙 Object saved and callbacks run, moving on")
+
+          finalize_object if @wizard.complete?
+        end
+
+        redirect_to send(@wizard.framework.edit_path_helper, @wizard.next_page.name.to_s.dasherize)
+      else
+        Rails.logger.debug("🧙 Object not valid, try again")
+
+        render :edit
+      end
+    end
+
+  private
+
+    def finalize_object(finalize: :finalize!)
+      Rails.logger.debug("🧙 Wizard complete, finalizing object")
+
+      if @wizard.object.respond_to?(finalize)
+        @wizard.object.send(finalize)
+        Rails.logger.debug("🧙 Wizard object finalized")
+      else
+        Rails.logger.warn("🧙 Wizard object has no #{finalize} method")
+      end
+    end
+
+    def check_wizard
+      @wizard.ensure_not_complete unless @wizard.current_page.is_a?(Wizardry::Pages::CompletionPage)
+    end
+
+    def setup_wizard
+      Rails.logger.debug("🧙 Finding or initialising #{wizard.class_name} with '#{identifier}'")
+
+      object = wizard.class_name.constantize.find_or_initialize_by(identifier: identifier)
+
+      Rails.logger.debug("🧙 Initialising the wizard 🪄")
+
+      @wizard = Wizardry::Instance.new(current_page: params[:page].underscore, object: object, framework: @framework)
+    end
+
+    def object_params
+      param_key = @wizard.framework.class_name.constantize.model_name.param_key
+
+      params.require(param_key).permit(@wizard.current_page.question_names)
+    rescue ActionController::ParameterMissing
+      { param_key => last_completed_step_params }
+    end
+
+    def last_completed_step_params
+      { last_completed_step: @wizard.current_page.name }
+    end
+
+    def identifier
+      cookies.fetch(wizard.cookie_name) { cookies[wizard.cookie_name] = SecureRandom.uuid }
+    end
+  end
+end

metadata

@@ -0,0 +1,251 @@
+--- !ruby/object:Gem::Specification
+name: govuk-wizardry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter Yates
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: govuk-components
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.3
+- !ruby/object:Gem::Dependency
+  name: govuk_design_system_formbuilder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.5
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0a2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.0.0a2
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails-controller-testing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-govuk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem that allows an entire GOV.UK wizard/journey to be easily defined
+  and built
+email:
+- peter.yates@graphia.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/helpers/wizardry_helper.rb
+- lib/tasks/wizardry_tasks.rake
+- lib/wizardry.rb
+- lib/wizardry/engine.rb
+- lib/wizardry/framework.rb
+- lib/wizardry/graph.rb
+- lib/wizardry/instance.rb
+- lib/wizardry/pages/check_your_answers_page.rb
+- lib/wizardry/pages/completion_page.rb
+- lib/wizardry/pages/page.rb
+- lib/wizardry/pages/question_page.rb
+- lib/wizardry/questions/answer.rb
+- lib/wizardry/questions/date.rb
+- lib/wizardry/questions/email_address.rb
+- lib/wizardry/questions/hidden.rb
+- lib/wizardry/questions/long_answer.rb
+- lib/wizardry/questions/radios.rb
+- lib/wizardry/questions/short_answer.rb
+- lib/wizardry/questions/telephone_number.rb
+- lib/wizardry/railtie.rb
+- lib/wizardry/routing/next_page.rb
+- lib/wizardry/version.rb
+homepage: https://www.github.com/graphia/wizardry
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: GOV.UK design system wizard generator
+test_files: []