katalyst-koi 4.18.0 → 5.0.0.alpha.1

data/app/components/koi/table_component.rb

@@ -3,5 +3,13 @@
 module Koi
   class TableComponent < Katalyst::TableComponent
     include Tables::Cells
+
+    def output_preamble
+      '<div class="table-container">'.html_safe + super
+    end
+
+    def output_postamble
+      super + "</div>".html_safe
+    end
   end
 end

data/app/controllers/admin/admin_users_controller.rb

@@ -2,9 +2,9 @@
 
 module Admin
   class AdminUsersController < ApplicationController
-    before_action :set_admin, only: %i[show edit update destroy]
+    before_action :set_admin_user, only: %i[show edit update destroy]
 
-    attr_reader :admin
+    attr_reader :admin_user
 
     def index
       collection = Collection.new.with_params(params).apply(Admin::User.strict_loading)
@@ -19,34 +19,34 @@ module Admin
     end
 
     def show
-      render :show, locals: { admin: }
+      render locals: { admin_user: }
     end
 
     def new
-      @admin = Admin::User.new
+      @admin_user = Admin::User.new
 
-      render :new, locals: { admin: }
+      render locals: { admin_user: }
     end
 
     def edit
-      render :edit, locals: { admin: }
+      render :edit, locals: { admin_user: }
     end
 
     def create
-      admin = Admin::User.new(admin_user_params)
+      admin_user = Admin::User.new(admin_user_params)
 
-      if admin.save
-        redirect_to admin_admin_user_path(admin)
+      if admin_user.save
+        redirect_to admin_admin_user_path(admin_user)
       else
-        render :new, locals: { admin: }, status: :unprocessable_content
+        render :new, locals: { admin_user: }, status: :unprocessable_content
       end
     end
 
     def update
-      if admin.update(admin_user_params)
+      if admin_user.update(admin_user_params)
         redirect_to action: :show
       else
-        render :edit, locals: { admin: }, status: :unprocessable_content
+        render :edit, locals: { admin_user: }, status: :unprocessable_content
       end
     end
 
@@ -63,21 +63,27 @@ module Admin
     end
 
     def destroy
-      admin.destroy
+      if admin_user.archived?
+        admin_user.destroy!
 
-      redirect_to admin_admin_users_path
+        redirect_to admin_admin_users_path
+      else
+        admin_user.archive!
+
+        redirect_back_or_to(admin_admin_user_path(admin_user), status: :see_other)
+      end
     end
 
     private
 
-    def set_admin
-      @admin = Admin::User.with_archived.find(params[:id])
+    def set_admin_user
+      @admin_user = Admin::User.with_archived.find(params[:id])
 
-      request.variant << :self if @admin == current_admin_user
+      request.variant << :self if admin_user == current_admin_user
     end
 
     def admin_user_params
-      params.expect(admin: %i[name email password archived])
+      params.expect(admin_user: %i[name email password archived])
     end
 
     class Collection < Admin::Collection

data/app/controllers/admin/application_controller.rb

@@ -2,8 +2,6 @@
 
 module Admin
   class ApplicationController < ActionController::Base
-    include Koi::Controller::IsAdminController
-
-    protect_from_forgery with: :exception
+    include Koi::Controller
   end
 end

data/app/controllers/admin/credentials_controller.rb

@@ -6,25 +6,29 @@ module Admin
 
     before_action :set_admin_user
 
+    attr_reader :admin_user
+
     def new
-      unless @admin_user.webauthn_id
-        @admin_user.update!(webauthn_id: WebAuthn.generate_user_id)
+      unless admin_user.webauthn_id
+        admin_user.update!(webauthn_id: WebAuthn.generate_user_id)
       end
 
       options = webauthn_relying_party.options_for_registration(
         user:    {
-          id:           @admin_user.webauthn_id,
-          name:         @admin_user.email,
-          display_name: @admin_user.to_s,
+          id:           admin_user.webauthn_id,
+          name:         admin_user.email,
+          display_name: admin_user.name,
         },
-        exclude: @admin_user.credentials.map(&:external_id),
+        exclude: admin_user.credentials.map(&:external_id),
       )
 
       # Store the newly generated challenge somewhere so you can have it
       # for the verification phase.
       session[:creation_challenge] = options.challenge
 
-      render :new, locals: { admin: @admin_user, options: }
+      credential = admin_user.credentials.new
+
+      render locals: { admin_user:, credential:, options: }
     end
 
     def create
@@ -35,7 +39,7 @@ module Admin
         session.delete(:creation_challenge),
       )
 
-      credential = @admin_user.credentials.find_or_initialize_by(
+      credential = admin_user.credentials.find_or_initialize_by(
         external_id: webauthn_credential.id,
       )
 
@@ -46,18 +50,18 @@ module Admin
       )
 
       respond_to do |format|
-        format.html { redirect_to admin_admin_user_path(@admin_user), status: :see_other }
-        format.turbo_stream { render locals: { admin: @admin_user } }
+        format.html { redirect_to admin_admin_user_path(admin_user), status: :see_other }
+        format.turbo_stream { render locals: { admin_user: } }
       end
     end
 
     def destroy
-      credential = @admin_user.credentials.find(params[:id])
+      credential = admin_user.credentials.find(params[:id])
       credential.destroy!
 
       respond_to do |format|
-        format.html { redirect_to admin_admin_user_path(@admin_user), status: :see_other }
-        format.turbo_stream { render locals: { admin: @admin_user } }
+        format.html { redirect_to admin_admin_user_path(admin_user), status: :see_other }
+        format.turbo_stream { render locals: { admin_user: } }
       end
     end
 
@@ -70,7 +74,7 @@ module Admin
     def set_admin_user
       @admin_user = Admin::User.find(params[:admin_user_id])
 
-      if current_admin == @admin_user
+      if current_admin == admin_user
         request.variant = :self
       else
         head(:forbidden)

data/app/controllers/admin/otps_controller.rb

@@ -4,45 +4,47 @@ module Admin
   class OtpsController < ApplicationController
     before_action :set_admin_user
 
+    attr_reader :admin_user
+
     def new
-      @admin_user.otp_secret = ROTP::Base32.random
+      admin_user.otp_secret = ROTP::Base32.random
 
-      render :new, locals: { admin: @admin_user }
+      render :new, locals: { admin_user: }
     end
 
     def create
-      @admin_user.otp_secret = otp_params[:otp_secret]
+      admin_user.otp_secret = otp_params[:otp_secret]
 
-      if @admin_user.otp.verify(otp_params[:token])
-        @admin_user.save
+      if admin_user.otp.verify(otp_params[:token])
+        admin_user.save
 
-        redirect_to admin_admin_user_path(@admin_user), status: :see_other
+        redirect_to admin_admin_user_path(admin_user), status: :see_other
       else
-        @admin_user.errors.add(:token, :invalid)
+        admin_user.errors.add(:token, :invalid)
 
         respond_to do |format|
-          format.html { redirect_to admin_admin_user_path(@admin_user), status: :see_other }
-          format.turbo_stream { render locals: { admin: @admin_user } }
+          format.html { redirect_to admin_admin_user_path(admin_user), status: :see_other }
+          format.turbo_stream { render locals: { admin_user: }, status: :unprocessable_entity }
         end
       end
     end
 
     def destroy
-      @admin_user.update!(otp_secret: nil)
+      admin_user.update!(otp_secret: nil)
 
-      redirect_to admin_admin_user_path(@admin_user), status: :see_other
+      redirect_to admin_admin_user_path(admin_user), status: :see_other
     end
 
     private
 
     def otp_params
-      params.expect(admin: %i[otp_secret token])
+      params.expect(admin_user: %i[otp_secret token])
     end
 
     def set_admin_user
       @admin_user = Admin::User.find(params[:admin_user_id])
 
-      if current_admin == @admin_user
+      if current_admin == admin_user
         request.variant = :self
       else
         head(:forbidden)

data/app/controllers/admin/sessions_controller.rb

@@ -6,7 +6,7 @@ module Admin
     include Koi::Controller::RecordsAuthentication
 
     before_action :redirect_authenticated, only: %i[new], if: :admin_signed_in?
-    before_action :authenticate_local_admin, only: %i[new], if: :authenticate_local_admins?
+    before_action :authenticate_local_admin, only: %i[new], if: -> { Koi.config.authenticate_local_admins? }
 
     layout "koi/login"
 
@@ -94,6 +94,17 @@ module Admin
       redirect_to(admin_dashboard_path, status: :see_other)
     end
 
+    def authenticate_local_admin
+      return if admin_signed_in? || !Rails.env.development?
+
+      session[:admin_user_id] =
+        Admin::User.where(email: %W[#{ENV.fetch('USER', nil)}@katalyst.com.au admin@katalyst.com.au]).first&.id
+
+      flash.delete(:redirect) if (redirect = flash[:redirect])
+
+      redirect_to(redirect || admin_dashboard_path, status: :see_other)
+    end
+
     def admin_sign_in(admin_user)
       record_sign_in!(admin_user)
 

data/app/controllers/admin/url_rewrites_controller.rb

@@ -4,68 +4,70 @@ module Admin
   class UrlRewritesController < ApplicationController
     before_action :set_url_rewrite, only: %i[show edit update destroy]
 
+    attr_reader :collection, :url_rewrite
+
     def index
-      collection = Collection.new.with_params(params).apply(UrlRewrite.strict_loading)
+      @collection = Collection.new.with_params(params).apply(UrlRewrite.strict_loading.all)
 
       render locals: { collection: }
     end
 
     def show
-      render :show, locals: { url_rewrite: @url_rewrite }
+      render locals: { url_rewrite: }
     end
 
     def new
       @url_rewrite = UrlRewrite.new
-      render :new, locals: { url_rewrite: @url_rewrite }
+
+      render locals: { url_rewrite: }
     end
 
     def edit
-      render :edit, locals: { url_rewrite: @url_rewrite }
+      render locals: { url_rewrite: }
     end
 
     def create
       @url_rewrite = UrlRewrite.new(url_rewrite_params)
 
       if @url_rewrite.save
-        redirect_to admin_url_rewrite_path(@url_rewrite)
+        redirect_to admin_url_rewrite_path(url_rewrite), status: :see_other
       else
-        render :new, status: :unprocessable_content, locals: { url_rewrite: @url_rewrite }
+        render :new, locals: { url_rewrite: }, status: :unprocessable_content
       end
     end
 
     def update
-      @url_rewrite.attributes = url_rewrite_params
-
-      if @url_rewrite.save
-        redirect_to admin_url_rewrite_path(@url_rewrite)
+      if url_rewrite.update(url_rewrite_params)
+        redirect_to admin_url_rewrite_path(url_rewrite), status: :see_other
       else
-        render :edit, status: :unprocessable_content, locals: { url_rewrite: @url_rewrite }
+        render :edit, locals: { url_rewrite: }, status: :unprocessable_content
       end
     end
 
     def destroy
       @url_rewrite.destroy!
 
-      redirect_to admin_url_rewrites_path
+      redirect_to admin_url_rewrites_path, status: :see_other
     end
 
     private
 
-    def url_rewrite_params
-      params.expect(url_rewrite: %i[from to status_code active])
+    def set_url_rewrite
+      @url_rewrite = ::UrlRewrite.find(params[:id])
     end
 
-    def set_url_rewrite
-      @url_rewrite = UrlRewrite.find(params[:id])
+    def url_rewrite_params
+      params.expect(url_rewrite: %i[from to active status_code])
     end
 
     class Collection < Admin::Collection
-      config.sorting  = "from"
+      config.sorting  = :from
       config.paginate = true
 
       attribute :from, :string
       attribute :to, :string
       attribute :active, :boolean
+      attribute :status_code, :enum
     end
   end
 end

data/app/controllers/admin/well_knowns_controller.rb

@@ -4,67 +4,69 @@ module Admin
   class WellKnownsController < ApplicationController
     before_action :set_well_known, only: %i[show edit update destroy]
 
+    attr_reader :collection, :well_known
+
     def index
-      collection = Collection.new.with_params(params).apply(::WellKnown.strict_loading.all)
+      @collection = Collection.new.with_params(params).apply(WellKnown.strict_loading.all)
 
       render locals: { collection: }
     end
 
     def show
-      render locals: { well_known: @well_known }
+      render locals: { well_known: }
     end
 
     def new
-      render locals: { well_known: ::WellKnown.new }
+      @well_known = WellKnown.new
+
+      render locals: { well_known: }
     end
 
     def edit
-      render locals: { well_known: @well_known }
+      render locals: { well_known: }
     end
 
     def create
-      @well_known = ::WellKnown.new(well_known_params)
+      @well_known = WellKnown.new(well_known_params)
 
       if @well_known.save
-        redirect_to [:admin, @well_known], status: :see_other
+        redirect_to admin_well_known_path(well_known), status: :see_other
       else
-        render :new, locals: { well_known: @well_known }, status: :unprocessable_content
+        render :new, locals: { well_known: }, status: :unprocessable_content
       end
     end
 
     def update
-      if @well_known.update(well_known_params)
-        redirect_to action: :show, status: :see_other
+      if well_known.update(well_known_params)
+        redirect_to admin_well_known_path(well_known), status: :see_other
       else
-        render :edit, locals: { well_known: @well_known }, status: :unprocessable_content
+        render :edit, locals: { well_known: }, status: :unprocessable_content
       end
     end
 
     def destroy
       @well_known.destroy!
 
-      redirect_to action: :index, status: :see_other
+      redirect_to admin_well_knowns_path, status: :see_other
     end
 
     private
 
-    # Only allow a list of trusted parameters through.
-    def well_known_params
-      params.expect(well_known: %i[name purpose content_type content])
-    end
-
-    # Use callbacks to share common setup or constraints between actions.
     def set_well_known
       @well_known = ::WellKnown.find(params[:id])
     end
 
+    def well_known_params
+      params.expect(well_known: %i[name purpose content_type content])
+    end
+
     class Collection < Admin::Collection
       config.sorting  = :name
       config.paginate = true
 
       attribute :name, :string
       attribute :purpose, :string
-      attribute :content_type, :string
+      attribute :content_type, :enum
       attribute :content, :string
     end
   end

data/app/controllers/concerns/koi/controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Koi
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      include HasAdminUsers
+      include HasAttachments
+      include Katalyst::Tables::Backend
+      include ::Pagy::Backend
+
+      default_form_builder "Koi::FormBuilder"
+      default_table_component "Koi::TableComponent"
+      default_table_query_component "Koi::TableQueryComponent"
+      default_summary_table_component "Koi::SummaryTableComponent"
+
+      # Dependency helpers
+      helper Katalyst::GOVUK::Formbuilder::Frontend
+      helper Katalyst::Navigation::FrontendHelper
+      helper Katalyst::Tables::Frontend
+      helper ::Pagy::Frontend
+
+      # Koi Helpers
+      helper FormHelper
+      helper HeaderHelper
+      helper Pagy::Frontend
+
+      # @deprecated to be removed in Koi 5
+      helper IndexActionsHelper
+
+      layout -> { turbo_frame_request? ? "koi/frame" : "koi/application" }
+
+      protect_from_forgery with: :exception
+    end
+  end
+end

data/app/helpers/koi/form_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Koi
+  module FormHelper
+    # Ensure that admin forms use `admin_` path helpers.
+    def form_with(model: false, url: nil, format: nil, **, &)
+      if model && (url != false)
+        url ||= if format.nil?
+                  polymorphic_path([:admin, model], {})
+                else
+                  polymorphic_path([:admin, model], format: format)
+                end
+      end
+
+      super
+    end
+  end
+end

data/app/helpers/koi/header_helper.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Koi
+  module HeaderHelper
+    # This helper generates an accessible breadcrumb navigation structure with
+    # proper ARIA attributes for screen readers. The breadcrumb items should be
+    # provided as content within the block.
+    #
+    # @param ** Additional HTML attributes to merge with the default breadcrumb attributes
+    # @yield [Block] The block should contain the breadcrumb items (typically `<li>` elements)
+    # @return [String, nil] Returns the HTML `<nav>` element with breadcrumbs if content is present, nil otherwise
+    #
+    # @example Basic usage with list items
+    #   <%= breadcrumb_list do %>
+    #     <li><%= link_to "Home", root_path %></li>
+    #     <li><%= link_to "Products", products_path %></li>
+    #   <% end %>
+    #
+    # @see https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/ ARIA breadcrumb pattern
+    def breadcrumb_list(**, &)
+      return if (content = capture(&)).blank?
+
+      tag.nav(**_koi_breadcrumbs_attributes(**)) do
+        tag.ol(content, class: "breadcrumbs-list", role: "list")
+      end
+    end
+
+    # This helper generates an accessible actions navigation structure with
+    # proper ARIA attributes for screen readers. The action items should be
+    # provided as content within the block.
+    #
+    # @param ** Additional HTML attributes to merge with the default actions attributes
+    # @yield [Block] The block should contain the action items (typically `<li>` elements)
+    # @return [String, nil] Returns the HTML `<nav>` element with actions if content is present, nil otherwise
+    #
+    # @example Basic usage with CRUD and contextual actions
+    #   <%= actions_list do %>
+    #     <li><%= link_to "Edit", edit_article_path(article) %></li>
+    #     <li><%= link_to_archive_or_delete(article) %></li>
+    #     <li><%= link_to "Config", articles_config_path(article) %></li>
+    #   <% end %>
+    #
+    # @see https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/ ARIA naming and descriptions
+    def actions_list(**, &)
+      return if (content = capture(&)).blank?
+
+      tag.nav(**_koi_actions_attributes(**)) do
+        tag.ul(content, class: "actions-list", role: "list")
+      end
+    end
+
+    # Creates a delete link with confirmation.
+    #
+    # @param model [ActiveRecord::Base] The record to create a delete link for
+    # @param text [String] Text to display for delete link (default: "Delete")
+    # @param confirm [String] Confirmation message for delete action (default: "Are you sure?")
+    # @param url [String] Target url for delete actions (defaults to admin_<record>_path)
+    # @param ** Additional HTML attributes to pass to the link
+    # @return [String, nil] Returns the HTML link element, or nil if record is not persisted
+    #
+    # @example Basic usage
+    #   <%= link_to_delete(user) %>
+    def link_to_delete(model,
+                       text = "Delete",
+                       confirm: "Are you sure?",
+                       url: polymorphic_path([:admin, model]),
+                       **)
+      return unless model.persisted?
+
+      link_to(text, url, data: { turbo_method: :delete, turbo_confirm: confirm }, **)
+    end
+
+    # Conditionally creates an archive or delete link based on the record's status.
+    #
+    # @param model [ActiveRecord::Base] The record to create an archive/delete link for
+    # @param archive_text [String] Text to display for archive link (default: "Archive")
+    # @param delete_text [String] Text to display for delete link (default: "Delete")
+    # @param confirm [String] Confirmation message for delete action (default: "Are you sure?")
+    # @param url [String] Target url for delete actions (defaults to admin_<record>_path)
+    # @param ** Additional HTML attributes to pass to the link
+    # @return [String, nil] Returns the HTML link element, or nil if record is not persisted
+    #
+    # @example Basic usage
+    #   <%= link_to_archive_or_delete(user) %>
+    #
+    # @see Koi::Model::Archivable For more information about the archivable concern
+    def link_to_archive_or_delete(model,
+                                  archive_text: "Archive",
+                                  delete_text: "Delete",
+                                  confirm: "Are you sure?",
+                                  url: polymorphic_path([:admin, model]),
+                                  **)
+      raise ArgumentError unless model.respond_to?(:archived?)
+
+      return unless model.persisted?
+
+      if model.archived?
+        link_to(delete_text, url, data: { turbo_method: :delete, turbo_confirm: confirm }, **)
+      else
+        link_to(archive_text, url, data: { turbo_method: :delete }, **)
+      end
+    end
+
+    private
+
+    using Katalyst::HtmlAttributes::HasHtmlAttributes
+
+    def _koi_breadcrumbs_attributes(**attributes)
+      {
+        aria:  { label: "Breadcrumb" },
+        class: "breadcrumb",
+      }.merge_html(attributes)
+    end
+
+    def _koi_actions_attributes(**attributes)
+      {
+        aria:  { label: "Actions" },
+        class: "actions",
+      }.merge_html(attributes)
+    end
+  end
+end

data/app/helpers/koi/index_actions_helper.rb

@@ -2,6 +2,7 @@
 
 module Koi
   module IndexActionsHelper
+    # @deprecated to be removed in Koi 5
     def koi_index_actions(search: false, create: false, &)
       IndexActionsBuilder.new(self, search:, create:).render(&)
     end
@@ -43,7 +44,7 @@ module Koi
     end
 
     def search(form)
-      tag.div class: "actions-group" do
+      tag.div class: "actions" do
         concat(search_button(form)) if search?
         concat(create_button(form)) if create?
         concat(search_input(form)) if search?
@@ -75,7 +76,7 @@ module Koi
     end
 
     def links(form, &)
-      tag.div(class: "actions-group") do
+      tag.div(class: "actions") do
         yield(form) if block_given?
       end
     end