undercarriage 0.5.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e851f84eca998dda6de087ad26e9f7c70965d821920d3414e2bfa0fd1a86fa6
-  data.tar.gz: 67afdb30e44dec5df059b2d00583b7bf6be28e33b3a0145671c8652f11fef72d
+  metadata.gz: 59a96756fb12afc085cd7e915c6c55d4795d354ba3e1206d2f2e4c600366f8ce
+  data.tar.gz: 18b7f4c033a3c1e0ec2b15be8a648dd6dd8c44cb77ea3df455a63b7376aa1fc0
 SHA512:
-  metadata.gz: 48a498285f452088b02057478f75db0e6290e4f0efed219bfd4550b4168fdd6673fe078966fd09d9f0fede51cb0b73d0909fc830c90cdac33e6c4a58cf96d803
-  data.tar.gz: b52b08d3e2c191c12d09149111cc12c131bd4044e35810b2db0be967a3717ef9d2b99c9b03100f1212aa4dfd9b2a080d841cd0b66555b8a1a0dd47c438269d03
+  metadata.gz: 0b22d67b2f8fddc1b9b5ab58205557e56c2e8ed1e4087092f265252ba573fc111f121c34b403e255556b03abde62dfe8046cb17711662f8c13cb7a9aba762003
+  data.tar.gz: b9c0d216a9c6e7455dad762f88dd13c953cc1dc251c4c3be6361b7d7e766882205878a52a923eaa81ace11762a09bd5cd3b670b85c8e3c0e07f4185513314097

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2021 David Freerksen
+Copyright 2026 David Freerksen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -2,28 +2,24 @@
 
 **\*Undercarriage is currently under development. It is not ready for production use.\***
 
-[![CircleCI](https://circleci.com/gh/dfreerksen/undercarriage.svg?style=shield)](https://circleci.com/gh/dfreerksen/undercarriage)
-[![Maintainability](https://api.codeclimate.com/v1/badges/d15980a534f8db936469/maintainability)](https://codeclimate.com/github/dfreerksen/undercarriage/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/d15980a534f8db936469/test_coverage)](https://codeclimate.com/github/dfreerksen/undercarriage/test_coverage)
-
 Undercarriage is a set of concerns to add to your application to trim some of the fat from controllers and models.
 
 ## Requirements
 
-* Ruby >= 2.5
+* Ruby >= 3.3.0
 * Rails >= 6.0
 
 ## Installation
 
 Add to your application's Gemfile
 
-```
-gem 'undercarriage', '~> 0.5'
+```bash
+gem 'undercarriage', '~> 1.0'
 ```
 
 Run the bundle command
 
-```
+```bash
 $ bundle install
 ```
 
@@ -31,35 +27,42 @@ $ bundle install
 
 TODO
 
-## TODO
-
-* [ ] Allow a way to set locale instead of relying on browser preferred language in `Undercarriage::Controllers::LocaleConcern`
-
 ## Testing
 
 Run tests with one of the following
 
-```
+```bash
 $ bundle exec rspec
 $ bundle exec rspec spec
 ```
 
 ### Appraisal
 
-Undercarriage uses [Appraisal](https://github.com/thoughtbot/appraisal) to ensure various dependency versions work as expected
+Undercarriage uses [Appraisal2](https://github.com/appraisal-rb/appraisal2) (a maintained fork of [Appraisal](https://github.com/thoughtbot/appraisal), still exposing the `appraisal` executable) to ensure various dependency versions work as expected
 
 When dependencies change, run
 
-```
+```bash
 $ bundle exec appraisal install
+$ bundle exec appraisal generate-install
 ```
 
 To run tests with Appraisal, run
 
-```
+```bash
 $ bundle exec appraisal rspec
 ```
 
+```bash
+$ bundle exec appraisal rails-6-0 rspec spec
+$ bundle exec appraisal rails-6-1 rspec spec
+$ bundle exec appraisal rails-7-0 rspec spec
+$ bundle exec appraisal rails-7-1 rspec spec
+$ bundle exec appraisal rails-7-2 rspec spec
+$ bundle exec appraisal rails-8-0 rspec spec
+$ bundle exec appraisal rails-8-1 rspec spec
+```
+
 ## Code Analysis
 
 Various tools are used to ensure code is linted and formatted correctly.
@@ -68,24 +71,32 @@ Various tools are used to ensure code is linted and formatted correctly.
 
 [RuboCop](https://github.com/bbatsov/rubocop) is a Ruby static code analyzer.
 
-```
+```bash
 $ rubocop
 ```
 
+### YARD-Lint
+
+[YARD-Lint](https://github.com/mensfeld/yard-lint) is a linter for YARD documentation.
+
+```bash
+$ bundle exec yard-lint
+```
+
 ## Documentation
 
 [Yard](https://github.com/lsegal/yard) is used to generate documentation. [Online documentation is available](http://www.rubydoc.info/github/dfreerksen/undercarriage/master)
 
 Build the documentation with one of the following
 
-```
+```bash
 $ yard
 $ yard doc
 ```
 
 Build the documentation and list all undocumented objects
 
-```
+```bash
 $ yard stats --list-undoc
 ```
 

data/Rakefile

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
 
 begin
-  require 'bundler/setup'
+  require "bundler/setup"
 rescue LoadError
-  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
 end
 
-require 'rdoc/task'
+require "rdoc/task"
 
 RDoc::Task.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Undercarriage'
-  rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.md')
-  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Undercarriage"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end
 
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"

data/lib/undercarriage/controllers/action_concern.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# :nodoc:
 module Undercarriage
   # :nodoc:
   module Controllers
@@ -8,11 +9,10 @@ module Undercarriage
     #
     # Helpers for the controller or view to help identify the action
     #
-    # Usage
+    # @example Controller
     #   class ExamplesController < ApplicationController
     #     include Undercarriage::Controllers::ActionConcern
     #   end
-    #
     module ActionConcern
       extend ActiveSupport::Concern
 
@@ -38,14 +38,13 @@ module Undercarriage
       #
       # Check if action is a certain action type
       #
-      # Usage
-      #   action?(:show) # true
-      #   action?('show') # true
-      #   action?(:index) # false
-      #
       # @param action_method [String, Symbol] the action to test
       # @return [Boolean] if action matches
       #
+      # @example View
+      #   action?(:show) # true
+      #   action?("show") # true
+      #   action?(:index) # false
       def action?(action_method)
         action == action_method.to_sym
       end
@@ -55,14 +54,13 @@ module Undercarriage
       #
       # Check if action is the index action type. The check will pass if it is an `index` action
       #
-      # Usage
-      #   index_action? # true
-      #   index_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   index_action? # true
+      #   index_action? # false
       def index_action?
-        action?('index')
+        action?("index")
       end
 
       ##
@@ -70,14 +68,13 @@ module Undercarriage
       #
       # Check if action is the show action type. The check will pass if it is a `show` action
       #
-      # Usage
-      #   show_action? # true
-      #   show_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   show_action? # true
+      #   show_action? # false
       def show_action?
-        action?('show')
+        action?("show")
       end
 
       ##
@@ -85,14 +82,13 @@ module Undercarriage
       #
       # Check if action is the new action type. The check will pass if it is a `new` action
       #
-      # Usage
-      #   new_action? # true
-      #   new_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   new_action? # true
+      #   new_action? # false
       def new_action?
-        action?('new')
+        action?("new")
       end
 
       ##
@@ -100,14 +96,13 @@ module Undercarriage
       #
       # Check if action is the create action type. The check will pass if it is a `create` action
       #
-      # Usage
-      #   create_action? # true
-      #   create_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   create_action? # true
+      #   create_action? # false
       def create_action?
-        action?('create')
+        action?("create")
       end
 
       ##
@@ -115,14 +110,13 @@ module Undercarriage
       #
       # Check if action is the edit action type. The check will pass if it is an `edit` action
       #
-      # Usage
-      #   edit_action? # true
-      #   edit_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   edit_action? # true
+      #   edit_action? # false
       def edit_action?
-        action?('edit')
+        action?("edit")
       end
 
       ##
@@ -130,14 +124,13 @@ module Undercarriage
       #
       # Check if action is the update action type. The check will pass if it is an `update` action
       #
-      # Usage
-      #   update_action? # true
-      #   update_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   update_action? # true
+      #   update_action? # false
       def update_action?
-        action?('update')
+        action?("update")
       end
 
       ##
@@ -145,14 +138,13 @@ module Undercarriage
       #
       # Check if action is the destroy action type. The check will pass if it is a `destroy` action
       #
-      # Usage
-      #   destroy_action? # true
-      #   destroy_action? # false
-      #
       # @return [Boolean] if action is action type
       #
+      # @example View
+      #   destroy_action? # true
+      #   destroy_action? # false
       def destroy_action?
-        action?('destroy')
+        action?("destroy")
       end
 
       ##
@@ -160,12 +152,11 @@ module Undercarriage
       #
       # Check if action is a collection action type. An action is a collection type if it is the `index` action
       #
-      # Usage
-      #   collection_action? # true
-      #   collection_action? # false
-      #
       # @return [Boolean] if action is collection type
       #
+      # @example View
+      #   collection_action? # true
+      #   collection_action? # false
       def collection_action?
         collection_actions.include?(action)
       end
@@ -175,15 +166,14 @@ module Undercarriage
       #
       # Check if action is a create or new action type. The check will pass if it is a `create` or `new` action
       #
-      # Usage
+      # @return [Boolean] if action is actions type
+      #
+      # @example View create
       #   create_actions? # true
       #   create_actions? # false
-      #
+      # @example View new
       #   new_actions? # true
       #   new_actions? # false
-      #
-      # @return [Boolean] if action is actions type
-      #
       def create_actions?
         create_actions.include?(action)
       end
@@ -195,12 +185,11 @@ module Undercarriage
       # Check if action is a member action type. An action is a member type if it is the `edit`, `show`, or `update`
       # action
       #
-      # Usage
-      #   member_action? # true
-      #   member_action? # false
-      #
       # @return [Boolean] if action is member type
       #
+      # @example View
+      #   member_action? # true
+      #   member_action? # false
       def member_action?
         member_actions.include?(action)
       end
@@ -210,15 +199,14 @@ module Undercarriage
       #
       # Check if action is an edit or update action type. The check will pass if it is an `edit` or `update` action
       #
-      # Usage
+      # @return [Boolean] if action is actions type
+      #
+      # @example View update
       #   update_actions? # true
       #   update_actions? # false
-      #
+      # @example View edit
       #   edit_actions? # true
       #   edit_actions? # false
-      #
-      # @return [Boolean] if action is actions type
-      #
       def update_actions?
         update_actions.include?(action)
       end
@@ -231,6 +219,7 @@ module Undercarriage
       #
       # Take `action_name` (string) and turn it into a symbol
       #
+      # @return [Symbol] action_name as a symbol
       def action
         action_name.to_sym
       end
@@ -238,6 +227,7 @@ module Undercarriage
       ##
       # Collection actions
       #
+      # @return [Array] collection actions
       def collection_actions
         %i[index]
       end
@@ -245,6 +235,7 @@ module Undercarriage
       ##
       # Member actions
       #
+      # @return [Array] member actions
       def member_actions
         %i[edit show update]
       end
@@ -252,6 +243,7 @@ module Undercarriage
       ##
       # Create actions
       #
+      # @return [Array] create actions
       def create_actions
         %i[create new]
       end
@@ -259,6 +251,7 @@ module Undercarriage
       ##
       # Update actions
       #
+      # @return [Array] update actions
       def update_actions
         %i[edit update]
       end

data/lib/undercarriage/controllers/kaminari_concern.rb

@@ -9,7 +9,7 @@ module Undercarriage
     # Helpers for Kaminari style pagination. Note that the Kaminari gem is not loaded with dependency. It must be added
     # to your own Gemfile
     #
-    # Usage
+    # @example Controller
     #   class ExamplesController < ApplicationController
     #     include Undercarriage::Controllers::KaminariConcern
     #
@@ -17,7 +17,6 @@ module Undercarriage
     #       @examples = Examples.page(page_num).per(per_page)
     #     end
     #   end
-    #
     module KaminariConcern
       extend ActiveSupport::Concern
 
@@ -33,12 +32,11 @@ module Undercarriage
       #
       # This is asseccible from the View as `per_page`
       #
-      # Usage
-      #   /examples?per=100 # Return 100 items per page
-      #   /examples?per=10&page=3 # Return page 3 of items with 10 items per page
-      #
       # @return [Integer] the number of items per page
       #
+      # @example Request
+      #   # GET /examples?per=100 # Return 100 items per page
+      #   # GET /examples?per=10&page=3 # Return page 3 of items with 10 items per page
       def per_page
         params.fetch(per_page_key, per_page_default).to_i
       end
@@ -50,12 +48,11 @@ module Undercarriage
       #
       # This is asseccible from the View as `page_num`
       #
-      # Usage
-      #   /examples?page=5 # Return page 5 of items
-      #   /examples?per=10&page=3 Return page 3 of items with 10 items per page
-      #
       # @return [Integer] the page number
       #
+      # @example Request
+      #   # GET /examples?page=5 # Return page 5 of items
+      #   # GET /examples?per=10&page=3 # Return page 3 of items with 10 items per page
       def page_num
         params.fetch(page_num_key, page_num_default).to_i
       end
@@ -67,6 +64,7 @@ module Undercarriage
       #
       # Query param to be used to identify count to be returned
       #
+      # @return [Integer] per page count
       def per_page_key
         :per
       end
@@ -76,16 +74,29 @@ module Undercarriage
       #
       # Query param to be used to identify page offset
       #
+      # @return [String,Symbol] page number key
       def page_num_key
         Kaminari.config.param_name
       end
 
       private
 
+      ##
+      # Items per page default
+      #
+      # Fallback used when the `per` query param is absent.
+      #
+      # @return [Integer] default per page count
       def per_page_default
         Kaminari.config.default_per_page
       end
 
+      ##
+      # Page number default
+      #
+      # Fallback used when the page query param is absent.
+      #
+      # @return [Integer] default page number
       def page_num_default
         1
       end

data/lib/undercarriage/controllers/locale_concern.rb

@@ -13,11 +13,10 @@ module Undercarriage
     # When preferred language cannot be identified or no translation is available, fall back to `I18n.default_locale`
     # (typically `en`).
     #
-    # Usage
+    # @example Controller
     #   class ExamplesController < ApplicationController
     #     include Undercarriage::Controllers::LocaleConcern
     #   end
-    #
     module LocaleConcern
       extend ActiveSupport::Concern
 
@@ -32,10 +31,11 @@ module Undercarriage
       #
       # Helper for Views to return the identified language.
       #
-      # Usage
-      #   <html lang="<%= html_lang %>"> #=> '<html lang="de">'
-      #   <html lang="<%= html_lang %>"> #=> '<html lang="de-at">'
+      # @return [String] locale for html tag lang attribute
       #
+      # @example View
+      #   # <html lang="<%= html_lang %>"> #=> '<html lang="de">'
+      #   # <html lang="<%= html_lang %>"> #=> '<html lang="de-at">'
       def html_lang
         I18n.locale.to_s
       end
@@ -54,14 +54,15 @@ module Undercarriage
       # * Persian/Farsi
       # * Urdu
       #
-      # Usage
-      #   <html dir="<%= html_dir %>"> #=> <html dir="ltr">
-      #   <html dir="<%= html_dir %>"> #=> <html dir="rtl">
+      # @return [String] direction for html tag dir attribute
       #
+      # @example View
+      #   # <html dir="<%= html_dir %>"> #=> <html dir="ltr">
+      #   # <html dir="<%= html_dir %>"> #=> <html dir="rtl">
       def html_dir
         rtl_languages = %w[am ar az dv fa he ur]
 
-        html_lang.start_with?(*rtl_languages) ? 'rtl' : 'ltr'
+        html_lang.start_with?(*rtl_languages) ? "rtl" : "ltr"
       end
 
       protected
@@ -71,12 +72,20 @@ module Undercarriage
       #
       # Set I18n locale for the request
       #
+      # @return [String] locale
       def identify_locale(&action)
         I18n.with_locale(first_available_locale, &action)
       end
 
       private
 
+      ##
+      # First available locale
+      #
+      # Intersects the request's accepted languages (falling back to `I18n.default_locale`) against
+      # `I18n.available_locales`, preferring the request's order.
+      #
+      # @return [String] locale
       def first_available_locale
         preferred_locales = (accepted_languages_header << I18n.default_locale.to_s).uniq
         available_locales = I18n.available_locales.map(&:to_s)
@@ -84,11 +93,18 @@ module Undercarriage
         (preferred_locales & available_locales).first
       end
 
+      ##
+      # Accepted languages header
+      #
+      # Parses the `HTTP_ACCEPT_LANGUAGE` request header into an ordered list of language tags, stripping any
+      # `;q=` quality values.
+      #
+      # @return [Array<String>] accepted language tags
       def accepted_languages_header
-        accepted_languages = request.env['HTTP_ACCEPT_LANGUAGE'] || ''
+        accepted_languages = request.env["HTTP_ACCEPT_LANGUAGE"] || ""
 
-        accepted_languages.gsub(/\s+/, '').split(',').map do |lang|
-          lang.split(';q=').first
+        accepted_languages.gsub(/\s+/, "").split(",").map do |lang|
+          lang.split(";q=").first
         end
       end
     end