undercarriage 0.5.7 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c80a0b92962c21262508fe3cfe89796a348e1b87c9e950d56e403ff114ba9c20
-  data.tar.gz: ec30e3665b643a807e05ca1f4ced57c385bceb5ae1a7dae6db16d72f429d0232
+  metadata.gz: b8d42d984572277bb1282c5fa0306028d91ced6801f88bb7ad36f01c05fcd8e8
+  data.tar.gz: f3d7690b1fdbf864395695f4a8651bbce2a907333430df01208edd0503419144
 SHA512:
-  metadata.gz: a276544a8b9343c1224d02918846fde1b426aa193a46557f3d52b2b82280c7d6ab5941a1dfe59ecefc02959c1bf72078cd19588aa01ea916dfe047b7c1b5344b
-  data.tar.gz: 134eec2dea285ff0a3de8521f9e0af1d2c20c4601ff1b2b07b7954a69ee00d1edb79b22939c635f7cdff9bdf4f610f248ce089142d7ccc81d04e075eaebc3407
+  metadata.gz: 6ee506e32efb9f323e4f5dcfd8494d00050dc0e20a9d4c09244440c0b7269cc52e5024878a91e24db6da67aa88908840931c0559d0ab7028f1a4cb7e932e61cc
+  data.tar.gz: 8577454663eaec4d8b20bd5f06bf36bc2d296cca855113e77b5f9b91c33908354f69aa33645e82ba14c3f45e154790008f4d2c309bf4943814ab5b2d8fd28078

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

@@ -1,71 +1,94 @@
 # Undercarriage
 
-**\*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.6
+* Ruby >= 3.0
 * Rails >= 6.0
 
 ## Installation
 
 Add to your application's Gemfile
 
-```
-gem 'undercarriage', '~> 0.5'
+```bash
+gem 'undercarriage', '~> 1.1'
 ```
 
 Run the bundle command
 
-```
+```bash
 $ bundle install
 ```
 
 ## Usage
 
-TODO
+Include `Undercarriage::Controllers::RestfulConcern` in a controller to get full RESTful `index`/`show`/`new`/`create`/`edit`/`update`/`destroy` actions, driven off the controller's own name/path:
+
+```ruby
+class PostsController < ApplicationController
+  include Undercarriage::Controllers::RestfulConcern
+
+  private
 
-## TODO
+  def permitted_attributes
+    [:title, :body]
+  end
+end
+```
+
+This infers `Post` as the model, sets `@posts`/`@post` as appropriate, and wires up flash messages, strong params, and redirects with no further code. Override the `*_content` hooks (e.g. `show_content`, `create_content`) or `after_create_action`/`after_update_action` to customize a single action without redefining it — see the YARD docs on each `Undercarriage::Controllers::Restful::*` concern for the full hook list.
+
+The standalone concerns can be included individually where you don't want the full RESTful stack:
+
+```ruby
+class ExamplesController < ApplicationController
+  include Undercarriage::Controllers::ActionConcern  # action?/index_action?/etc. view helpers
+  include Undercarriage::Controllers::KaminariConcern # page_num/per_page params for Kaminari
+  include Undercarriage::Controllers::LocaleConcern   # I18n.locale from HTTP_ACCEPT_LANGUAGE
+end
+
+class Example < ApplicationRecord
+  include Undercarriage::Models::PublishedConcern # published/unpublished scopes
+end
+```
 
-* [ ] Allow a way to set locale instead of relying on browser preferred language in `Undercarriage::Controllers::LocaleConcern`
-* [ ] Add support for Rails 5.2
+See the YARD documentation linked below for every concern's options and examples.
 
 ## 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
 ```
 
-To run tests with a specific version of Appraisal, run
-
-```
-$ bundle exec appraisal rails-60 rspec
-$ bundle exec appraisal rails-61 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
@@ -76,24 +99,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
 
@@ -29,35 +28,36 @@ module Undercarriage
       # Items per page
       #
       # The number of items to return in pagination. Will use the Kaminari config `default_per_page` (typically `25`)
-      # for the count and will look for `per` in the URL paramaters to override.
+      # for the count and will look for `per` in the URL paramaters to override. The result is clamped between `1`
+      # and {#per_page_max} so a caller cannot force an unbounded (or negative/zero) number of records per page.
       #
       # 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
+      #   # GET /examples?per=999999999 # Clamped down to per_page_max
       def per_page
-        params.fetch(per_page_key, per_page_default).to_i
+        params.fetch(per_page_key, per_page_default).to_i.clamp(1, per_page_max)
       end
 
       ##
       # Page number
       #
-      # Will look for the Kaminari config `param_name` (typically `page`) in the URL paramaters.
+      # Will look for the Kaminari config `param_name` (typically `page`) in the URL paramaters. The result is
+      # clamped to a minimum of `1` so a caller cannot force a negative or zero page number.
       #
       # 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
+        params.fetch(page_num_key, page_num_default).to_i.clamp(1, nil)
       end
 
       protected
@@ -67,6 +67,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,19 +77,43 @@ 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
+
+      ##
+      # Items per page maximum
+      #
+      # Upper bound enforced on {#per_page} regardless of what the `per` query param requests. Defaults to the
+      # Kaminari config `max_per_page` when set, otherwise `100`. Override to allow a different ceiling.
+      #
+      # @return [Integer] maximum per page count
+      def per_page_max
+        Kaminari.config.max_per_page || 100
+      end
     end
   end
 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