concerns_on_rails 1.11.0 → 1.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a34c6e186b582806890012bb0f8bf049c1fd0f56f74007af7669cdb5ae713eb2
-  data.tar.gz: 298f957409be23ecfd9bbd0de46161ac56af7a01a6a300d29cf3bff9ca2b94d3
+  metadata.gz: 9eb1080168652222770c2ea933745175091c64599ea39e309220a9be8b241b1c
+  data.tar.gz: f39962ffb8a0e359d2137f1df9440be0a58a17d8c05d78181ba17d2ae1d0433b
 SHA512:
-  metadata.gz: 6a96e094791d487cd9a534e4263de4bd902af9b533a8607ceb20906d4b38827c82ee0b370cb885d8a5800aef8a03a9b84cc718dc00074da1c0b1f35ade4fc2b3
-  data.tar.gz: e803d31da5694c6ad1a0ea28d928f9d552e75ded84420aa94cb816538e4cbe9b4a228f2b9dfa9428a8091b369444909d750523d2c5a0e9edae1f2df6fec95a78
+  metadata.gz: ee0491e22fe01259415dbc266d19b9a2e966c53e9f0a0b3acded0aa5dd60e2e7085faeeff0b7995e6d6e1849612f1611a551bd2dbb5837f2757cb0de25ebfb72
+  data.tar.gz: 6297b08086c0b8417eff076393d725e40d6e469780fb8d60e5525a1b3a3a53d57fa44a6e90457f4625a7ed7012494cb80d385e5138c8b6e8b7d4836e0ed79cdd

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 <!-- CHANGELOG.md -->
 
+## 1.11.2 (2026-06-06)
+
+### Added
+- **Models::Taggable**: Lightweight, dependency-free tagging over a single string column (no join tables, no tagging engine; works on any database including SQLite). `taggable_by :tags` adds `tag_list` get/set (accepts a String or an Array, stripped + de-duped), `add_tags` / `remove_tags`, a `tagged_with?` predicate, a boundary-safe `tagged_with(*tags, any:)` class scope (AND by default, OR with `any: true`), and `all_tags`. Options: `delimiter:` and `downcase:`. Reach for `acts-as-taggable-on` when you need tag contexts, ownership, or tag clouds.
+- **Models::SoftDeletable**: `soft_deletable_by` gained `default_scope:` (default `true`) to opt out of the deleted-hiding `default_scope`; new explicit `soft_delete_all` class method (preferred over the `destroy_all` override).
+- **Models::Sluggable**: `sluggable_by` gained `reserved_words:` (reject slugs like `new` / `edit` / `admin` — saving such a record fails validation) and `finders: true` (`Model.find` accepts a slug directly), layering friendly_id's `:reserved` / `:finders` modules.
+- **Models::Sortable**: `sortable_by` now threads acts_as_list's `scope:` (independent position sequence per group) and `add_new_at:` (`:top` / `:bottom`) options through to `acts_as_list`.
+
+### Fixed
+- **Models::SoftDeletable**: `soft_delete!` / `restore!` (and the bulk `soft_delete_all` / `restore_all` / `destroy_all`) now run inside a transaction, so a raising `before_*` / `after_*` hook rolls the timestamp change back instead of leaving a half-applied state — adopting `discard`'s transactional playbook.
+
+### Notes
+- All changes are backward-compatible: the soft-delete `default_scope` stays on by default and `destroy_all` continues to soft-delete. New models are encouraged to set `default_scope: false` and use the explicit `soft_delete_all`.
+
+## 1.11.1 (2026-06-05)
+
+### Added
+- **Models::Addressable**: `addressable_by` gained four options:
+  - `lengths:` — per-part length limits (`{ line1: 100, city: 3..50 }`); an Integer is a positive maximum, a Range is `min..max` (inclusive/exclusive, endless, and beginless all supported). Length is measured on the normalized value; messages mirror Rails (singular/plural). Bad bounds raise an `ArgumentError` at load time.
+  - `allow_blank:` — per-field opt-out (an Array of parts, or `true`) for the length check when a value is blank. Independent of `required:`.
+  - `normalize_country:` — opt-in canonicalization of a country value to its ISO 3166-1 alpha-2 code: a recognized English name (`"Canada"`) or 3-letter alpha-3 (`"CAN"`) maps to the alpha-2 (`"CA"`); unrecognized values are left untouched. Lets postal/state validation recognize a named country.
+  - `if:` / `unless:` — standard Rails validation conditions (Symbol, Proc, or Array) gating the address validations. Normalization still runs unconditionally.
+
+### Fixed
+- **Models::Addressable**: a present-but-unrecognized country (e.g. a full name with `normalize_country` off, or an invalid code) no longer borrows the `default_country`'s postal/state rules. It now falls back to the permissive postal pattern and skips state validation, so valid foreign postal codes aren't rejected against the wrong country. `default_country` still applies when the country column is absent or blank.
+
+### Internal
+- **Support::AddressData**: added `COUNTRY_DATA` (all 249 ISO 3166-1 countries → `[name, alpha-3]`) as the single source of truth; `ISO_COUNTRY_CODES` and the name / alpha-3 lookups are derived from it, and a new `normalize_country_code` backs the country normalization.
+
 ## 1.10.0 (2026-06-03)
 
 ### Added

data/README.md

@@ -39,6 +39,7 @@ Article.published.without_deleted.find("hello-world")
   - [Sequenceable](#-sequenceable) — ordered, human-friendly reference numbers
   - [Stateable](#-stateable) — lightweight string-backed state machine
   - [Addressable](#-addressable) — postal address normalization + format validation
+  - [Taggable](#-taggable) — lightweight tagging over a single column
 - **Controller concerns**
   - [Paginatable](#-paginatable) — offset pagination with headers
   - [Filterable](#-filterable) — declarative URL-param filters
@@ -55,7 +56,7 @@ Article.published.without_deleted.find("hello-world")
 
 ## ✨ Why this gem?
 
-- **Fourteen model concerns + six controller concerns**, all production-ready
+- **Fifteen model concerns + six controller concerns**, all production-ready
 - **One include, one macro** — no boilerplate, no glue code
 - **Lean dependencies** — only `acts_as_list` (Sortable) and `friendly_id` (Sluggable); controller concerns have zero extra deps
 - **Schema-validated configuration** — every macro checks that the configured column exists and raises `ArgumentError` early
@@ -158,6 +159,13 @@ Post.friendly.find("old-slug")   # still resolves to the renamed post
 
 # Unique slug only within a scope column (same slug allowed in different accounts)
 sluggable_by :title, scope: :account_id
+
+# Reject reserved slugs — saving a record whose slug would be reserved fails validation
+sluggable_by :title, reserved_words: %w[new edit admin]
+
+# Let Model.find accept a slug directly (not just the id)
+sluggable_by :title, finders: true
+Post.find("hello-world")   # resolves by slug
 ```
 
 **Notes**
@@ -191,6 +199,8 @@ Task.last.move_higher
 sortable_by :priority                       # ascending priority
 sortable_by priority: :desc                 # descending priority
 sortable_by :position, use_acts_as_list: false   # just the default_scope ordering, no acts_as_list
+sortable_by :position, scope: :list_id           # independent position sequence per list (acts_as_list scope:)
+sortable_by :position, add_new_at: :top          # new rows insert at the top (acts_as_list add_new_at:)
 ```
 
 **Notes**
@@ -246,7 +256,7 @@ publishable_by :published_at, default_scope: true
 
 ## ❌ SoftDeletable
 
-Soft delete records using a timestamp field (default: `deleted_at`). Includes a `default_scope` that hides deleted records and overrides `destroy_all` to soft-delete in bulk.
+Soft delete records using a timestamp field (default: `deleted_at`). By default a `default_scope` hides deleted records — **opt out** with `soft_deletable_by :deleted_at, default_scope: false` and chain `.without_deleted` explicitly (the safer choice for new models, avoiding `default_scope`'s join/uniqueness footguns). `soft_delete!` / `restore!` and the bulk helpers run inside a transaction, so a raising hook rolls the change back.
 
 ```ruby
 class User < ApplicationRecord
@@ -280,11 +290,14 @@ User.unscoped             # everything (deleted + non-deleted)
 **Bulk operations**
 
 ```ruby
-User.destroy_all          # soft-deletes all matching records
+User.soft_delete_all      # soft-deletes all matching records (explicit — preferred)
+User.destroy_all          # alias of soft_delete_all (kept for backwards compatibility)
 User.really_destroy_all   # hard-deletes all matching records
 User.restore_all          # restores all soft-deleted records
 ```
 
+All of these run in a transaction, so a raising hook rolls the whole batch back.
+
 **Lifecycle hooks** — override these methods on the model:
 
 ```ruby
@@ -725,6 +738,9 @@ class Place < ApplicationRecord
                  required:        %i[line1 city postal_code country],
                  default_country: "GB",                       # country used when the record has none
                  validate_state:  true,                       # opt-in US/CA state-code check
+                 lengths:         { line1: 100, city: 50, postal_code: 5..10 }, # max (Int) or min..max (Range)
+                 allow_blank:     %i[state],                   # these parts skip the length check when blank
+                 normalize_country: true,                      # "Canada"/"CAN" -> "CA" (off by default)
                  verify_with:     ->(rec) { Usps.verify(rec) } # opt-in external verifier
 end
 ```
@@ -735,20 +751,25 @@ end
 |-------------------|--------------------------------------|---------------------------------------------------------------------|
 | `line1:` … `country:` | same-named columns               | Map each canonical part to a real column. Missing columns are skipped. |
 | `required:`       | `%i[line1 city postal_code country]` | Parts (by canonical name) that must be present. Each must map to an existing column. |
-| `default_country:`| `"US"`                               | Country used to pick the postal-code format when the record has no recognized country. |
+| `default_country:`| `"US"`                               | Postal-code format used when the country column is **absent or blank**. A present-but-unrecognized country value falls back to the permissive pattern instead — see the postal note below. |
 | `validate_state:` | `false`                              | When `true`, validates the state against US / CA code sets.         |
+| `lengths:`        | `{}`                                 | Per-part length limits: `{ line1: 100, city: 50, postal_code: 5..10 }`. An Integer is a (positive) maximum; a Range is `min..max` (non-negative, satisfiable; endless `3..` and beginless `..50` allowed). Only the parts you list are checked. Bad bounds raise an `ArgumentError` at load time. |
+| `allow_blank:`    | `false`                              | Per-field opt-out for the length check: an Array of parts (e.g. `%i[line2 state]`), or `true` for all parts. A blank value for an allowed part skips its length check. Independent of `required:`. |
+| `normalize_country:` | `false`                           | When `true`, canonicalize the country to its ISO 3166-1 alpha-2 code: an English name (`"Canada"`, `"United States"`) or a 3-letter alpha-3 (`"CAN"`, `"USA"`) maps to the alpha-2 (`"CA"`, `"US"`); unrecognized values are left untouched. This also lets postal/state validation recognize a named country. |
 | `verify_with:`    | `nil`                                | A callable for real-world verification (see below).                 |
+| `if:` / `unless:` | `nil`                                | Standard Rails validation conditions (Symbol, Proc, or Array) gating the address **validations** — e.g. `if: :on_addresses?`. Normalization still runs unconditionally. |
 
 **What it normalizes** (in `before_validation`)
 - Text parts: `strip` + `squish`.
 - `postal_code`: squish + upcase, with canonical spacing for CA (`A1A1A1` → `A1A 1A1`).
-- `country` / `state`: upcased when they look like a 2-letter code (full names left alone).
+- `country` / `state`: upcased when they look like a 2-letter code (full names left alone). With `normalize_country: true`, a recognized ISO country name or alpha-3 code is canonicalized to its alpha-2 (`"Canada"`/`"CAN"` → `"CA"`); unrecognized values are left as-is.
 
 **What it validates**
 - Presence of every `required:` part.
 - `country`: a 2-letter value must be a real ISO 3166-1 alpha-2 code.
-- `postal_code`: matched against a per-country pattern (US, CA, GB, AU, DE, FR) with a permissive fallback for everything else.
+- `postal_code`: matched against a per-country pattern (US, CA, GB, AU, DE, FR) with a permissive fallback for everything else. A strict per-country pattern is only applied when the country is a recognized ISO alpha-2 code (or `default_country` when the country column is absent/blank); a present-but-unrecognized country (e.g. a full name like `"Canada"`) uses the permissive pattern, so valid foreign codes aren't rejected against the wrong country.
 - `state`: only when `validate_state: true` and the country is US/CA.
+- `lengths`: each listed part's length (measured on the **normalized** value) must fit its `min..max` (Integer = max only). Errors mirror Rails, including singular/plural: `"is too short (minimum is N characters)"` / `"is too long (maximum is 1 character)"`. A blank value satisfies a max-only rule and, by default, **fails a minimum greater than 0** — list the part in `allow_blank:` to skip the check when blank. `allow_blank` is independent of `required:`: presence is still governed solely by `required:`, so a required part with a minimum that's left blank reports both `"can't be blank"` and `"is too short …"`. Note length is counted *after* normalization, so a CA `postal_code` includes the inserted space (`"A1A 1A1"` is 7) — size limits accordingly.
 
 **External verification (`verify_with:`)** — runs **only after** structural validation passes, so you never spend an API call on an obviously-broken address. The callable receives the record and may either add to `record.errors` itself, or return:
 
@@ -767,6 +788,45 @@ end
 
 ---
 
+## 🏷️ Taggable
+
+Lightweight, dependency-free tagging stored in a **single string column** — no join tables, no tagging engine. Works on any database, including SQLite.
+
+```ruby
+class Article < ApplicationRecord
+  include ConcernsOnRails::Taggable
+
+  taggable_by :tags                      # default column :tags
+  # taggable_by :skills, downcase: true  # custom column, case-folded
+end
+
+article = Article.new
+article.tag_list = "Ruby, Rails, Ruby"   # accepts a String or an Array
+article.tag_list                          # => ["Ruby", "Rails"]  (stripped + de-duped)
+article.add_tags("api")
+article.remove_tags("Rails")
+article.tagged_with?("ruby")              # => membership predicate
+article.save!
+
+Article.tagged_with("ruby", "rails")          # records carrying BOTH tags
+Article.tagged_with("ruby", "go", any: true)  # records carrying ANY tag
+Article.all_tags                               # => sorted unique tags in use
+```
+
+**Options**
+
+| Option       | Default | Purpose                                                          |
+|--------------|---------|------------------------------------------------------------------|
+| `delimiter:` | `","`   | Character joining the stored tags (a tag must not contain it).    |
+| `downcase:`  | `false` | Case-fold tags on write so matching is case-insensitive.          |
+
+**Notes**
+- Matching is **boundary-safe** — searching `rail` does not match `rails`. An explicit SQL `ESCAPE` clause makes tags containing `_` / `%` match literally on every adapter.
+- Tags are normalized in `before_validation`, so a direct `record.tags = "a, b"` assignment is cleaned too. An empty list stores `NULL`.
+- Reach for [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) when you need tag contexts, ownership, counts/clouds, or polymorphic tags shared across models.
+
+---
+
 # 🎮 Controller Concerns
 
 Pure ActionController + ActiveRecord — **zero extra runtime dependencies** (no Kaminari, Pundit, or Ransack).
@@ -1015,13 +1075,29 @@ Both forms reference the same module, so you can freely mix them.
 
 ---
 
+## 🧭 Philosophy & when to reach for a dedicated gem
+
+`concerns_on_rails` aims to cover the common 80% of each behavior with **one `include` + one declarative macro**, **schema-validated** configuration, **no-surprise defaults**, and **lean dependencies** (only `acts_as_list` and `friendly_id`; controller concerns have none). It is deliberately *not* a re-implementation of the category leaders — reach for a dedicated gem when you outgrow the basics:
+
+| Need | Use instead |
+|------|-------------|
+| Complex state machines (callbacks, transition logging) | [`aasm`](https://github.com/aasm/aasm) |
+| Association-cascade soft delete / sentinel-aware unique indexes | [`paranoia`](https://github.com/rubysherpas/paranoia) or [`discard`](https://github.com/jhawthorn/discard) |
+| Tagging with contexts, ownership, or tag clouds | [`acts-as-taggable-on`](https://github.com/mbleigh/acts-as-taggable-on) |
+| Full-text search with ranking / stemming | [`pg_search`](https://github.com/Casecommons/pg_search) / Elasticsearch |
+| Audit trails / version history | [`paper_trail`](https://github.com/paper-trail-gem/paper_trail) / [`audited`](https://github.com/collectiveidea/audited) |
+
+`Sluggable` wraps [`friendly_id`](https://github.com/norman/friendly_id) and `Sortable` wraps [`acts_as_list`](https://github.com/brendon/acts_as_list), so you get those leaders' engines behind the declarative macro.
+
+---
+
 ## 🛠️ Development
 
 ```sh
 bundle install                                  # install dev dependencies
 bundle exec rspec                               # run the test suite
 gem build concerns_on_rails.gemspec             # build the gem
-gem install ./concerns_on_rails-1.11.0.gem      # install locally
+gem install ./concerns_on_rails-1.11.2.gem      # install locally
 ```
 
 The test suite uses an in-memory SQLite database and a lightweight `FakeController` harness for controller-concern specs — no Rails routes or boot required.

data/lib/concerns_on_rails/legacy_aliases.rb

@@ -16,4 +16,5 @@ module ConcernsOnRails
   Stateable     = Models::Stateable
   Addressable   = Models::Addressable
   Sequenceable  = Models::Sequenceable
+  Taggable      = Models::Taggable
 end

data/lib/concerns_on_rails/models/addressable.rb

@@ -13,7 +13,10 @@ module ConcernsOnRails
     #     addressable_by                      # standard line1/line2/city/state/postal_code/country columns
     #     # addressable_by line1: :street, postal_code: :zip, country: :country_code,
     #     #                required: %i[line1 city postal_code], default_country: "GB",
-    #     #                validate_state: true, verify_with: ->(rec) { Usps.verify(rec) }
+    #     #                validate_state: true, verify_with: ->(rec) { Usps.verify(rec) },
+    #     #                lengths: { line1: 100, postal_code: 5..10 }, allow_blank: %i[state],
+    #     #                normalize_country: true,  # "Canada"/"CAN" -> "CA"
+    #     #                if: :on_addresses?        # Rails-style condition gating the validations
     #   end
     #
     # Scope is *format/structure* only — it checks shape, not real-world
@@ -31,15 +34,23 @@ module ConcernsOnRails
       # Parts required by default (each must map to an existing column).
       DEFAULT_REQUIRED = %i[line1 city postal_code country].freeze
 
+      # Prefix for the ArgumentErrors raised during configuration.
+      LABEL = "ConcernsOnRails::Models::Addressable".freeze
+
       included do
         class_attribute :addressable_fields, instance_accessor: false, default: {}
         class_attribute :addressable_required, instance_accessor: false, default: [].freeze
         class_attribute :addressable_default_country, instance_accessor: false, default: "US"
         class_attribute :addressable_validate_state, instance_accessor: false, default: false
         class_attribute :addressable_verifier, instance_accessor: false, default: nil
+        class_attribute :addressable_lengths, instance_accessor: false, default: {}
+        class_attribute :addressable_allow_blank, instance_accessor: false, default: [].freeze
+        class_attribute :addressable_normalize_country, instance_accessor: false, default: false
+        class_attribute :addressable_validation_registered, instance_accessor: false, default: false
 
+        # `validate :validate_address` is registered by `addressable_by` (not here) so it can
+        # carry the optional if:/unless: condition. Normalization always runs.
         before_validation :normalize_address
-        validate :validate_address
       end
 
       # Defined as a real module (not `class_methods do`) so the public macro and
@@ -51,23 +62,29 @@ module ConcernsOnRails
         # Configure the address. Column overrides are passed as `part: :column`
         # keyword pairs; everything else tunes behavior. See the module docs.
         def addressable_by(required: DEFAULT_REQUIRED, default_country: "US",
-                           validate_state: false, verify_with: nil, **mapping)
+                           validate_state: false, verify_with: nil,
+                           lengths: {}, allow_blank: false, normalize_country: false, **mapping)
+          condition = extract_validation_condition!(mapping)
           self.addressable_fields = resolve_addressable_fields(mapping)
           self.addressable_required = Array(required).map(&:to_sym)
           self.addressable_default_country = default_country.to_s.upcase
           self.addressable_validate_state = validate_state
           self.addressable_verifier = verify_with
+          self.addressable_lengths = resolve_lengths(lengths)
+          self.addressable_allow_blank = resolve_allow_blank(allow_blank)
+          self.addressable_normalize_country = normalize_country
           ensure_required_columns!
+          register_address_validation(condition)
         end
 
         private
 
         def resolve_addressable_fields(mapping)
           unknown = mapping.keys.map(&:to_sym) - DEFAULT_FIELDS.keys
-          raise ArgumentError, "ConcernsOnRails::Models::Addressable: unknown address part(s): #{unknown.join(', ')}" if unknown.any?
+          raise ArgumentError, "#{LABEL}: unknown address part(s): #{unknown.join(', ')}" if unknown.any?
 
           overrides = mapping.to_h { |part, column| [part.to_sym, column.to_sym] }
-          ensure_columns!("ConcernsOnRails::Models::Addressable", overrides.values)
+          ensure_columns!(LABEL, overrides.values)
           DEFAULT_FIELDS.merge(overrides).select { |_part, column| column_names.include?(column.to_s) }
         end
 
@@ -76,9 +93,86 @@ module ConcernsOnRails
           return if missing.empty?
 
           raise ArgumentError,
-                "ConcernsOnRails::Models::Addressable: required address part(s) #{missing.join(', ')} " \
+                "#{LABEL}: required address part(s) #{missing.join(', ')} " \
                 "have no matching column (table: #{table_name})"
         end
+
+        # Normalize the lengths: option into { part => [min, max] }, where min
+        # defaults to 0 and max to Infinity so the validator needs no nil guards.
+        def resolve_lengths(lengths)
+          raise ArgumentError, "#{LABEL}: lengths: must be a Hash (part => Integer or Range)" unless lengths.is_a?(Hash)
+
+          lengths.to_h do |part, bound|
+            sym = part.to_sym
+            raise ArgumentError, "#{LABEL}: unknown address part in lengths: #{sym}" unless DEFAULT_FIELDS.key?(sym)
+
+            [sym, normalize_length_bound(sym, bound)]
+          end
+        end
+
+        def normalize_length_bound(part, bound)
+          case bound
+          when Integer
+            raise ArgumentError, "#{LABEL}: lengths[#{part}] must be a positive Integer" unless bound.positive?
+
+            [0, bound]
+          when Range then range_bounds(part, bound)
+          else
+            raise ArgumentError, "#{LABEL}: lengths[#{part}] must be an Integer or Range, got #{bound.class}"
+          end
+        end
+
+        # A Range becomes [min, max] (min defaults to 0, an open end becomes
+        # Infinity). Bounds must be non-negative Integers and the range must be
+        # satisfiable (min <= max) — otherwise a typo would silently brick a column.
+        def range_bounds(part, range)
+          min = range.begin || 0
+          max = range.end
+          validate_range_endpoints!(part, min, max)
+          max -= 1 if max && range.exclude_end?
+          max ||= Float::INFINITY
+          raise ArgumentError, "#{LABEL}: lengths[#{part}] range is empty or inverted (#{range})" if min > max
+
+          [min, max]
+        end
+
+        def validate_range_endpoints!(part, min, max)
+          return if min.is_a?(Integer) && !min.negative? && (max.nil? || (max.is_a?(Integer) && !max.negative?))
+
+          raise ArgumentError, "#{LABEL}: lengths[#{part}] range must have non-negative Integer bounds"
+        end
+
+        # Normalize allow_blank: into the list of parts whose length check is skipped when blank.
+        def resolve_allow_blank(allow_blank)
+          case allow_blank
+          when true then DEFAULT_FIELDS.keys
+          when false, nil then []
+          when Array
+            parts = allow_blank.map(&:to_sym)
+            unknown = parts - DEFAULT_FIELDS.keys
+            raise ArgumentError, "#{LABEL}: unknown address part(s) in allow_blank: #{unknown.join(', ')}" if unknown.any?
+
+            parts
+          else
+            raise ArgumentError, "#{LABEL}: allow_blank: must be true, false, or an Array of parts"
+          end
+        end
+
+        # Pull Rails-style `if:` / `unless:` out of the keyword args (they ride in via
+        # **mapping) so the remaining keys are treated as column overrides.
+        def extract_validation_condition!(mapping)
+          { if: mapping.delete(:if), unless: mapping.delete(:unless) }.compact
+        end
+
+        # Register `validate :validate_address` once, forwarding any if:/unless: condition
+        # straight to Rails so it behaves like a normal conditional validation. Normalization
+        # (before_validation) is unconditional; the condition only gates the validations.
+        def register_address_validation(condition)
+          return if addressable_validation_registered
+
+          self.addressable_validation_registered = true
+          validate :validate_address, **condition
+        end
       end
 
       # --- Normalization (before_validation) ------------------------------------
@@ -97,6 +191,7 @@ module ConcernsOnRails
 
       def validate_address
         validate_required_parts
+        validate_lengths
         validate_country_code
         validate_postal_code
         validate_state_code if self.class.addressable_validate_state
@@ -141,26 +236,46 @@ module ConcernsOnRails
         DEFAULT_FIELDS.keys.select { |part| self.class.addressable_fields.key?(part) }
       end
 
-      # The 2-letter country code driving postal/state checks: the record's own
-      # country when it's a recognized code, otherwise the configured default.
+      # The country driving postal-/state-format selection:
+      #   * the record's own country when it's a recognized ISO alpha-2 code
+      #   * the configured default_country when the country column is absent or blank
+      #   * nil ("unknown") when a country is present but unrecognized — so postal/state
+      #     fall back to permissive checks instead of wrongly applying the default's rules
       def resolved_country
         column = self.class.addressable_fields[:country]
         value = column && self[column]
-        return self.class.addressable_default_country unless value.is_a?(String)
+        return self.class.addressable_default_country if value.blank?
 
-        code = value.strip.upcase
-        ConcernsOnRails::Support::AddressData.valid_country?(code) ? code : self.class.addressable_default_country
+        code = canonical_country_code(value)
+        ConcernsOnRails::Support::AddressData.valid_country?(code) ? code : nil
+      end
+
+      # The country value as an alpha-2 candidate, applying name/alpha-3 mapping
+      # when normalize_country is on so postal/state checks recognize it too.
+      def canonical_country_code(value)
+        return ConcernsOnRails::Support::AddressData.normalize_country_code(value).to_s.upcase if self.class.addressable_normalize_country
+
+        value.to_s.strip.upcase
       end
 
       def normalize_part(part, country, value)
         squished = value.strip.squish
         case part
         when :postal_code then ConcernsOnRails::Support::AddressData.normalize_postal(country, value)
-        when :country, :state then squished.length == 2 ? squished.upcase : squished
+        when :country then normalize_country_part(squished)
+        when :state then squished.length == 2 ? squished.upcase : squished
         else squished
         end
       end
 
+      # With normalize_country on, map a name/alpha-3 to its alpha-2 (leaving an
+      # unrecognized value untouched); otherwise just upcase a bare 2-letter code.
+      def normalize_country_part(squished)
+        return ConcernsOnRails::Support::AddressData.normalize_country_code(squished) if self.class.addressable_normalize_country
+
+        squished.length == 2 ? squished.upcase : squished
+      end
+
       def validate_required_parts
         fields = self.class.addressable_fields
         self.class.addressable_required.each do |part|
@@ -169,6 +284,31 @@ module ConcernsOnRails
         end
       end
 
+      def validate_lengths
+        self.class.addressable_lengths.each { |part, bounds| validate_length_of(part, bounds) }
+      end
+
+      # Enforce one part's [min, max] bounds. A blank value skips the check only
+      # when the part is in allow_blank; otherwise the minimum is enforced on blanks
+      # (independent of required:). Length is measured on the normalized value.
+      def validate_length_of(part, (min, max))
+        column = self.class.addressable_fields[part]
+        return unless column
+
+        value = self[column]
+        return if value.blank? && self.class.addressable_allow_blank.include?(part)
+
+        length = value.to_s.length
+        errors.add(column, "is too short (minimum is #{length_phrase(min)})") if length < min
+        errors.add(column, "is too long (maximum is #{length_phrase(max)})") if length > max
+      end
+
+      # "1 character" / "N characters" — mirrors Rails' pluralized length errors
+      # without depending on i18n. (max is only interpolated for finite bounds.)
+      def length_phrase(count)
+        "#{count} #{count == 1 ? 'character' : 'characters'}"
+      end
+
       def validate_country_code
         column = self.class.addressable_fields[:country]
         value = column && self[column]

data/lib/concerns_on_rails/models/sluggable.rb

@@ -34,27 +34,40 @@ module ConcernsOnRails
         # Define sluggable field, with optional friendly_id features.
         # Example:
         #   sluggable_by :wonderful_name
-        #   sluggable_by :title, history: true       # old slugs keep resolving (needs a friendly_id_slugs table)
-        #   sluggable_by :title, scope: :account_id  # slugs unique per scope column
-        def sluggable_by(field, history: false, scope: nil)
+        #   sluggable_by :title, history: true            # old slugs keep resolving (needs a friendly_id_slugs table)
+        #   sluggable_by :title, scope: :account_id       # slugs unique per scope column
+        #   sluggable_by :title, reserved_words: %w[new]  # block these slugs (a UUID is appended instead)
+        #   sluggable_by :title, finders: true            # Model.find accepts a slug directly
+        def sluggable_by(field, history: false, scope: nil, reserved_words: nil, finders: false)
           self.sluggable_field = field.to_sym
           ensure_columns!("ConcernsOnRails::Models::Sluggable", [sluggable_field, scope].compact)
-          reconfigure_friendly_id(history: history, scope: scope) if history || scope
+          return unless history || scope || reserved_words || finders
+
+          reconfigure_friendly_id(history: history, scope: scope,
+                                  reserved_words: reserved_words, finders: finders)
         end
 
         private
 
         # Re-runs friendly_id with the extra modules. friendly_id merges config
-        # across calls, so this layers :history / :scoped onto the base :slugged.
-        def reconfigure_friendly_id(history:, scope:)
+        # across calls, so this layers :history / :scoped / :finders / :reserved onto :slugged.
+        def reconfigure_friendly_id(history:, scope:, reserved_words: nil, finders: false)
           modules = [:slugged]
           modules << :history if history
           modules << :scoped if scope
-          options = { use: modules }
-          options[:scope] = scope if scope
+          modules << :finders if finders
+          modules << :reserved if reserved_words
           # friendly_id's second argument is a positional options hash (not kwargs),
           # so pass it positionally to stay correct on both Ruby 2.7 and 3.x.
-          friendly_id(:slug_source, options)
+          friendly_id(:slug_source, friendly_id_options(modules, scope, reserved_words))
+        end
+
+        # Build friendly_id's positional options hash from the resolved modules.
+        def friendly_id_options(modules, scope, reserved_words)
+          options = { use: modules }
+          options[:scope] = scope if scope
+          options[:reserved_words] = Array(reserved_words).map(&:to_s) if reserved_words
+          options
         end
       end
 

data/lib/concerns_on_rails/models/soft_deletable.rb

@@ -9,6 +9,11 @@ module ConcernsOnRails
         # declare class attributes and set default values
         class_attribute :soft_delete_field, instance_accessor: false, default: :deleted_at
         class_attribute :soft_delete_touch, instance_accessor: false, default: true
+        # Whether `.all` hides soft-deleted rows via a default_scope. ON by default for
+        # backwards compatibility; opt out with `soft_deletable_by ..., default_scope: false`.
+        # A default_scope is sticky and breaks unscoped joins / uniqueness validations /
+        # eager-loading, so new models are encouraged to disable it and chain `.without_deleted`.
+        class_attribute :soft_delete_default_scope, instance_accessor: false, default: true
 
         # scopes
         scope :active, -> { unscope(where: soft_delete_field).where(soft_delete_field => nil) }
@@ -19,25 +24,35 @@ module ConcernsOnRails
         scope :with_deleted, -> { unscope(where: soft_delete_field) }
         # Records soft-deleted within the last `duration` (e.g. `deleted_within(7.days)`).
         scope :deleted_within, ->(duration) { soft_deleted.where(soft_delete_field => duration.ago..) }
-        # Optionally, uncomment to hide deleted by default:
-        default_scope { without_deleted }
+
+        # Hide soft-deleted rows from `.all` only when enabled (the default). The block is
+        # evaluated lazily, so toggling `soft_delete_default_scope` via the macro takes effect.
+        default_scope { soft_delete_default_scope ? without_deleted : all }
       end
 
       class_methods do
         include ConcernsOnRails::Support::ColumnGuard
 
-        # Define soft delete field and options
+        # Define soft delete field and options.
         # Example:
         #   soft_deletable_by :deleted_at, touch: false
-        def soft_deletable_by(field = nil, touch: true)
+        #   soft_deletable_by :deleted_at, default_scope: false  # don't hide deleted rows from .all
+        def soft_deletable_by(field = nil, touch: true, default_scope: true)
           self.soft_delete_field = field || :deleted_at
           self.soft_delete_touch = touch
+          self.soft_delete_default_scope = default_scope
           ensure_columns!("ConcernsOnRails::Models::SoftDeletable", soft_delete_field)
         end
 
-        # Override destroy_all to perform soft delete on all records
+        # Soft-delete every matching record, wrapped in a transaction so the batch is atomic.
+        def soft_delete_all
+          transaction { all.each(&:soft_delete!) }
+        end
+
+        # Override destroy_all to soft delete. Kept for backwards compatibility, but prefer the
+        # explicit `soft_delete_all` — silently redefining a standard AR method is a known footgun.
         def destroy_all
-          all.each(&:soft_delete!)
+          soft_delete_all
         end
 
         # Provide really_destroy_all to hard delete all records
@@ -45,9 +60,9 @@ module ConcernsOnRails
           unscoped.delete_all
         end
 
-        # Restore every soft-deleted record (mirror of the destroy_all override).
+        # Restore every soft-deleted record, atomically (mirror of soft_delete_all).
         def restore_all
-          soft_deleted.each(&:restore!)
+          transaction { soft_deleted.each(&:restore!) }
         end
       end
 
@@ -60,26 +75,34 @@ module ConcernsOnRails
       def soft_delete!
         return true if deleted?
 
-        before_soft_delete
-        result = if self.class.soft_delete_touch
-                   update(self.class.soft_delete_field => Time.zone.now)
-                 else
-                   update_column(self.class.soft_delete_field, Time.zone.now)
-                 end
-        after_soft_delete if result
+        result = false
+        # Wrap the timestamp change and its hooks in a transaction so a raising
+        # before/after hook rolls the change back instead of leaving a half-applied state.
+        transaction do
+          before_soft_delete
+          result = if self.class.soft_delete_touch
+                     update(self.class.soft_delete_field => Time.zone.now)
+                   else
+                     update_column(self.class.soft_delete_field, Time.zone.now)
+                   end
+          after_soft_delete if result
+        end
         result
       end
 
       def restore!
         return true unless deleted?
 
-        before_restore
-        result = if self.class.soft_delete_touch
-                   update(self.class.soft_delete_field => nil)
-                 else
-                   update_column(self.class.soft_delete_field, nil)
-                 end
-        after_restore if result
+        result = false
+        transaction do
+          before_restore
+          result = if self.class.soft_delete_touch
+                     update(self.class.soft_delete_field => nil)
+                   else
+                     update_column(self.class.soft_delete_field, nil)
+                   end
+          after_restore if result
+        end
         result
       end
 

data/lib/concerns_on_rails/models/sortable.rb

@@ -34,14 +34,16 @@ module ConcernsOnRails
       class_methods do
         include ConcernsOnRails::Support::ColumnGuard
 
-        # Define sortable field and direction
+        # Define sortable field and direction.
         # Example:
         #   sortable_by :position
         #   sortable_by position: :asc
         #   sortable_by position: :desc
         #
         #   sortable_by :position, use_acts_as_list: false
-        def sortable_by(field_config = nil, use_acts_as_list: true, **field_options)
+        #   sortable_by :position, scope: :list_id        # independent ordering within each list
+        #   sortable_by :position, add_new_at: :top       # new records go to the top of the list
+        def sortable_by(field_config = nil, use_acts_as_list: true, scope: nil, add_new_at: nil, **field_options)
           field_config = field_options if field_config.nil? && field_options.any?
 
           # parse field_config
@@ -56,7 +58,14 @@ module ConcernsOnRails
 
           ensure_columns!("ConcernsOnRails::Models::Sortable", sortable_field)
 
-          acts_as_list column: sortable_field if use_acts_as_list
+          return unless use_acts_as_list
+
+          # Thread acts_as_list's own options through (scope: for per-group ordering,
+          # add_new_at: for where freshly-inserted rows land).
+          list_options = { column: sortable_field }
+          list_options[:scope] = scope unless scope.nil?
+          list_options[:add_new_at] = add_new_at unless add_new_at.nil?
+          acts_as_list(list_options)
         end
 
         private

data/lib/concerns_on_rails/models/taggable.rb

@@ -0,0 +1,160 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Models
+    # Lightweight, dependency-free tagging over a single string column.
+    # Tags are stored delimiter-joined in one column — no join tables, no
+    # tagging engine — so it works on any database, including SQLite.
+    #
+    #   class Article < ApplicationRecord
+    #     include ConcernsOnRails::Taggable
+    #
+    #     taggable_by :tags                       # default column :tags
+    #     # taggable_by :skills, downcase: true   # custom column, case-folded
+    #   end
+    #
+    #   a = Article.new
+    #   a.tag_list = "Ruby, Rails, Ruby"          # accepts a String or an Array
+    #   a.tag_list                                 # => ["Ruby", "Rails"]  (stripped + de-duped)
+    #   a.add_tags("api"); a.remove_tags("Rails")
+    #   a.tagged_with?("ruby")                     # membership predicate
+    #   a.save!
+    #
+    #   Article.tagged_with("ruby", "rails")          # records carrying BOTH tags
+    #   Article.tagged_with("ruby", "go", any: true)  # records carrying ANY tag
+    #   Article.all_tags                               # sorted unique tags in use
+    #
+    # Notes:
+    #   * Matching is boundary-safe ("rail" does not match "rails").
+    #   * A tag must not contain the delimiter (default ",").
+    #   * Reach for acts-as-taggable-on when you need tag contexts, ownership,
+    #     tag counts/clouds, or polymorphic tags shared across models.
+    module Taggable
+      extend ActiveSupport::Concern
+
+      LABEL = "ConcernsOnRails::Models::Taggable".freeze
+      DEFAULT_FIELD = :tags
+      DEFAULT_DELIMITER = ",".freeze
+
+      included do
+        class_attribute :taggable_field, instance_accessor: false, default: DEFAULT_FIELD
+        class_attribute :taggable_delimiter, instance_accessor: false, default: DEFAULT_DELIMITER
+        class_attribute :taggable_downcase, instance_accessor: false, default: false
+      end
+
+      # Real module (not `class_methods do`) so the private query helpers live
+      # under a single `private`. ActiveSupport::Concern auto-extends ClassMethods.
+      module ClassMethods
+        include ConcernsOnRails::Support::ColumnGuard
+
+        # Configure the tag column. See the module docs for the DSL.
+        def taggable_by(field = DEFAULT_FIELD, delimiter: DEFAULT_DELIMITER, downcase: false)
+          self.taggable_field = field.to_sym
+          self.taggable_delimiter = delimiter.to_s
+          self.taggable_downcase = downcase
+          ensure_columns!(LABEL, taggable_field)
+
+          before_validation :taggable_normalize!
+        end
+
+        # Records carrying the given tags. `any: true` matches ANY tag (OR);
+        # the default requires ALL tags (AND). Returns a chainable relation.
+        def tagged_with(*names, any: false)
+          tags = taggable_clean_all(names)
+          return all if tags.empty?
+
+          clauses = tags.map { |t| taggable_clause(t) }
+          sql = clauses.map(&:first).join(any ? " OR " : " AND ")
+          where(sql, *clauses.flat_map(&:last))
+        end
+
+        # All distinct tags currently stored across the table, sorted.
+        def all_tags
+          pluck(taggable_field).flat_map { |raw| taggable_split(raw) }.uniq.sort
+        end
+
+        # Split a raw stored column value into a normalized tag array.
+        def taggable_split(raw)
+          taggable_clean_all(raw.to_s.split(taggable_delimiter))
+        end
+
+        # Normalize a single tag (strip + optional downcase).
+        def taggable_clean(tag)
+          tag = tag.to_s.strip
+          taggable_downcase ? tag.downcase : tag
+        end
+
+        private
+
+        def taggable_clean_all(names)
+          names.flatten.map { |t| taggable_clean(t) }.reject(&:blank?).uniq
+        end
+
+        # Boundary-safe match for one tag against the delimiter-joined column.
+        # Returns [sql_fragment, [bind_params...]]. An explicit ESCAPE clause makes
+        # the backslash escaping below work on every adapter (SQLite has no default
+        # LIKE escape), so a tag containing `_` or `%` matches literally.
+        def taggable_clause(tag)
+          column = "#{connection.quote_table_name(table_name)}.#{connection.quote_column_name(taggable_field)}"
+          delim = taggable_delimiter
+          escaped = taggable_escape_like(tag)
+          esc = " ESCAPE '\\'"
+          ["(#{column} = ? OR #{column} LIKE ?#{esc} OR #{column} LIKE ?#{esc} OR #{column} LIKE ?#{esc})",
+           [tag, "#{escaped}#{delim}%", "%#{delim}#{escaped}", "%#{delim}#{escaped}#{delim}%"]]
+        end
+
+        # Treat the user's tag as a LIKE literal: %, _ and \ are not wildcards.
+        def taggable_escape_like(str)
+          str.gsub(/[\\%_]/) { |char| "\\#{char}" }
+        end
+      end
+
+      # ---- instance methods ----
+
+      def tag_list
+        self.class.taggable_split(self[self.class.taggable_field])
+      end
+
+      def tag_list=(value)
+        tags = taggable_coerce(value)
+        self[self.class.taggable_field] = tags.empty? ? nil : tags.join(self.class.taggable_delimiter)
+      end
+
+      def add_tags(*names)
+        self.tag_list = tag_list + names.flatten.map { |t| self.class.taggable_clean(t) }
+        tag_list
+      end
+      alias add_tag add_tags
+
+      def remove_tags(*names)
+        drop = names.flatten.map { |t| self.class.taggable_clean(t) }
+        self.tag_list = tag_list.reject { |t| drop.include?(t) }
+        tag_list
+      end
+      alias remove_tag remove_tags
+
+      def tagged_with?(tag)
+        tag_list.include?(self.class.taggable_clean(tag))
+      end
+      alias has_tag? tagged_with?
+
+      private
+
+      # before_validation hook — re-normalize whatever sits in the column, covering
+      # direct `record.tags = "..."` assignment, not just the tag_list= setter.
+      def taggable_normalize!
+        field = self.class.taggable_field
+        raw = self[field]
+        return if raw.nil?
+
+        tags = self.class.taggable_split(raw)
+        self[field] = tags.empty? ? nil : tags.join(self.class.taggable_delimiter)
+      end
+
+      def taggable_coerce(value)
+        items = value.is_a?(Array) ? value : value.to_s.split(self.class.taggable_delimiter)
+        items.map { |t| self.class.taggable_clean(t) }.reject(&:blank?).uniq
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/support/address_data.rb

@@ -10,34 +10,270 @@ module ConcernsOnRails
     module AddressData
       module_function
 
-      # ISO 3166-1 alpha-2 country codes.
-      ISO_COUNTRY_CODES = Set.new(%w[
-                                    AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ
-                                    BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ
-                                    CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ
-                                    DE DJ DK DM DO DZ
-                                    EC EE EG EH ER ES ET
-                                    FI FJ FK FM FO FR
-                                    GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY
-                                    HK HM HN HR HT HU
-                                    ID IE IL IM IN IO IQ IR IS IT
-                                    JE JM JO JP
-                                    KE KG KH KI KM KN KP KR KW KY KZ
-                                    LA LB LC LI LK LR LS LT LU LV LY
-                                    MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ
-                                    NA NC NE NF NG NI NL NO NP NR NU NZ
-                                    OM
-                                    PA PE PF PG PH PK PL PM PN PR PS PT PW PY
-                                    QA
-                                    RE RO RS RU RW
-                                    SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ
-                                    TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ
-                                    UA UG UM US UY UZ
-                                    VA VC VE VG VI VN VU
-                                    WF WS
-                                    YE YT
-                                    ZA ZM ZW
-                                  ]).freeze
+      # Source of truth for ISO 3166-1: alpha-2 => [English name, alpha-3].
+      # ISO_COUNTRY_CODES and the name/alpha-3 lookups below are all derived
+      # from this, so the three never drift apart.
+      # Each value is a [name, alpha-3] pair (a tuple), not a list of words.
+      # rubocop:disable Style/WordArray
+      COUNTRY_DATA = {
+        "AD" => ["Andorra", "AND"],
+        "AE" => ["United Arab Emirates", "ARE"],
+        "AF" => ["Afghanistan", "AFG"],
+        "AG" => ["Antigua and Barbuda", "ATG"],
+        "AI" => ["Anguilla", "AIA"],
+        "AL" => ["Albania", "ALB"],
+        "AM" => ["Armenia", "ARM"],
+        "AO" => ["Angola", "AGO"],
+        "AQ" => ["Antarctica", "ATA"],
+        "AR" => ["Argentina", "ARG"],
+        "AS" => ["American Samoa", "ASM"],
+        "AT" => ["Austria", "AUT"],
+        "AU" => ["Australia", "AUS"],
+        "AW" => ["Aruba", "ABW"],
+        "AX" => ["Åland Islands", "ALA"],
+        "AZ" => ["Azerbaijan", "AZE"],
+        "BA" => ["Bosnia and Herzegovina", "BIH"],
+        "BB" => ["Barbados", "BRB"],
+        "BD" => ["Bangladesh", "BGD"],
+        "BE" => ["Belgium", "BEL"],
+        "BF" => ["Burkina Faso", "BFA"],
+        "BG" => ["Bulgaria", "BGR"],
+        "BH" => ["Bahrain", "BHR"],
+        "BI" => ["Burundi", "BDI"],
+        "BJ" => ["Benin", "BEN"],
+        "BL" => ["Saint Barthélemy", "BLM"],
+        "BM" => ["Bermuda", "BMU"],
+        "BN" => ["Brunei", "BRN"],
+        "BO" => ["Bolivia", "BOL"],
+        "BQ" => ["Caribbean Netherlands", "BES"],
+        "BR" => ["Brazil", "BRA"],
+        "BS" => ["Bahamas", "BHS"],
+        "BT" => ["Bhutan", "BTN"],
+        "BV" => ["Bouvet Island", "BVT"],
+        "BW" => ["Botswana", "BWA"],
+        "BY" => ["Belarus", "BLR"],
+        "BZ" => ["Belize", "BLZ"],
+        "CA" => ["Canada", "CAN"],
+        "CC" => ["Cocos (Keeling) Islands", "CCK"],
+        "CD" => ["Democratic Republic of the Congo", "COD"],
+        "CF" => ["Central African Republic", "CAF"],
+        "CG" => ["Republic of the Congo", "COG"],
+        "CH" => ["Switzerland", "CHE"],
+        "CI" => ["Côte d'Ivoire", "CIV"],
+        "CK" => ["Cook Islands", "COK"],
+        "CL" => ["Chile", "CHL"],
+        "CM" => ["Cameroon", "CMR"],
+        "CN" => ["China", "CHN"],
+        "CO" => ["Colombia", "COL"],
+        "CR" => ["Costa Rica", "CRI"],
+        "CU" => ["Cuba", "CUB"],
+        "CV" => ["Cape Verde", "CPV"],
+        "CW" => ["Curaçao", "CUW"],
+        "CX" => ["Christmas Island", "CXR"],
+        "CY" => ["Cyprus", "CYP"],
+        "CZ" => ["Czechia", "CZE"],
+        "DE" => ["Germany", "DEU"],
+        "DJ" => ["Djibouti", "DJI"],
+        "DK" => ["Denmark", "DNK"],
+        "DM" => ["Dominica", "DMA"],
+        "DO" => ["Dominican Republic", "DOM"],
+        "DZ" => ["Algeria", "DZA"],
+        "EC" => ["Ecuador", "ECU"],
+        "EE" => ["Estonia", "EST"],
+        "EG" => ["Egypt", "EGY"],
+        "EH" => ["Western Sahara", "ESH"],
+        "ER" => ["Eritrea", "ERI"],
+        "ES" => ["Spain", "ESP"],
+        "ET" => ["Ethiopia", "ETH"],
+        "FI" => ["Finland", "FIN"],
+        "FJ" => ["Fiji", "FJI"],
+        "FK" => ["Falkland Islands", "FLK"],
+        "FM" => ["Micronesia", "FSM"],
+        "FO" => ["Faroe Islands", "FRO"],
+        "FR" => ["France", "FRA"],
+        "GA" => ["Gabon", "GAB"],
+        "GB" => ["United Kingdom", "GBR"],
+        "GD" => ["Grenada", "GRD"],
+        "GE" => ["Georgia", "GEO"],
+        "GF" => ["French Guiana", "GUF"],
+        "GG" => ["Guernsey", "GGY"],
+        "GH" => ["Ghana", "GHA"],
+        "GI" => ["Gibraltar", "GIB"],
+        "GL" => ["Greenland", "GRL"],
+        "GM" => ["Gambia", "GMB"],
+        "GN" => ["Guinea", "GIN"],
+        "GP" => ["Guadeloupe", "GLP"],
+        "GQ" => ["Equatorial Guinea", "GNQ"],
+        "GR" => ["Greece", "GRC"],
+        "GS" => ["South Georgia and the South Sandwich Islands", "SGS"],
+        "GT" => ["Guatemala", "GTM"],
+        "GU" => ["Guam", "GUM"],
+        "GW" => ["Guinea-Bissau", "GNB"],
+        "GY" => ["Guyana", "GUY"],
+        "HK" => ["Hong Kong", "HKG"],
+        "HM" => ["Heard Island and McDonald Islands", "HMD"],
+        "HN" => ["Honduras", "HND"],
+        "HR" => ["Croatia", "HRV"],
+        "HT" => ["Haiti", "HTI"],
+        "HU" => ["Hungary", "HUN"],
+        "ID" => ["Indonesia", "IDN"],
+        "IE" => ["Ireland", "IRL"],
+        "IL" => ["Israel", "ISR"],
+        "IM" => ["Isle of Man", "IMN"],
+        "IN" => ["India", "IND"],
+        "IO" => ["British Indian Ocean Territory", "IOT"],
+        "IQ" => ["Iraq", "IRQ"],
+        "IR" => ["Iran", "IRN"],
+        "IS" => ["Iceland", "ISL"],
+        "IT" => ["Italy", "ITA"],
+        "JE" => ["Jersey", "JEY"],
+        "JM" => ["Jamaica", "JAM"],
+        "JO" => ["Jordan", "JOR"],
+        "JP" => ["Japan", "JPN"],
+        "KE" => ["Kenya", "KEN"],
+        "KG" => ["Kyrgyzstan", "KGZ"],
+        "KH" => ["Cambodia", "KHM"],
+        "KI" => ["Kiribati", "KIR"],
+        "KM" => ["Comoros", "COM"],
+        "KN" => ["Saint Kitts and Nevis", "KNA"],
+        "KP" => ["North Korea", "PRK"],
+        "KR" => ["South Korea", "KOR"],
+        "KW" => ["Kuwait", "KWT"],
+        "KY" => ["Cayman Islands", "CYM"],
+        "KZ" => ["Kazakhstan", "KAZ"],
+        "LA" => ["Laos", "LAO"],
+        "LB" => ["Lebanon", "LBN"],
+        "LC" => ["Saint Lucia", "LCA"],
+        "LI" => ["Liechtenstein", "LIE"],
+        "LK" => ["Sri Lanka", "LKA"],
+        "LR" => ["Liberia", "LBR"],
+        "LS" => ["Lesotho", "LSO"],
+        "LT" => ["Lithuania", "LTU"],
+        "LU" => ["Luxembourg", "LUX"],
+        "LV" => ["Latvia", "LVA"],
+        "LY" => ["Libya", "LBY"],
+        "MA" => ["Morocco", "MAR"],
+        "MC" => ["Monaco", "MCO"],
+        "MD" => ["Moldova", "MDA"],
+        "ME" => ["Montenegro", "MNE"],
+        "MF" => ["Saint Martin", "MAF"],
+        "MG" => ["Madagascar", "MDG"],
+        "MH" => ["Marshall Islands", "MHL"],
+        "MK" => ["North Macedonia", "MKD"],
+        "ML" => ["Mali", "MLI"],
+        "MM" => ["Myanmar", "MMR"],
+        "MN" => ["Mongolia", "MNG"],
+        "MO" => ["Macao", "MAC"],
+        "MP" => ["Northern Mariana Islands", "MNP"],
+        "MQ" => ["Martinique", "MTQ"],
+        "MR" => ["Mauritania", "MRT"],
+        "MS" => ["Montserrat", "MSR"],
+        "MT" => ["Malta", "MLT"],
+        "MU" => ["Mauritius", "MUS"],
+        "MV" => ["Maldives", "MDV"],
+        "MW" => ["Malawi", "MWI"],
+        "MX" => ["Mexico", "MEX"],
+        "MY" => ["Malaysia", "MYS"],
+        "MZ" => ["Mozambique", "MOZ"],
+        "NA" => ["Namibia", "NAM"],
+        "NC" => ["New Caledonia", "NCL"],
+        "NE" => ["Niger", "NER"],
+        "NF" => ["Norfolk Island", "NFK"],
+        "NG" => ["Nigeria", "NGA"],
+        "NI" => ["Nicaragua", "NIC"],
+        "NL" => ["Netherlands", "NLD"],
+        "NO" => ["Norway", "NOR"],
+        "NP" => ["Nepal", "NPL"],
+        "NR" => ["Nauru", "NRU"],
+        "NU" => ["Niue", "NIU"],
+        "NZ" => ["New Zealand", "NZL"],
+        "OM" => ["Oman", "OMN"],
+        "PA" => ["Panama", "PAN"],
+        "PE" => ["Peru", "PER"],
+        "PF" => ["French Polynesia", "PYF"],
+        "PG" => ["Papua New Guinea", "PNG"],
+        "PH" => ["Philippines", "PHL"],
+        "PK" => ["Pakistan", "PAK"],
+        "PL" => ["Poland", "POL"],
+        "PM" => ["Saint Pierre and Miquelon", "SPM"],
+        "PN" => ["Pitcairn Islands", "PCN"],
+        "PR" => ["Puerto Rico", "PRI"],
+        "PS" => ["Palestine", "PSE"],
+        "PT" => ["Portugal", "PRT"],
+        "PW" => ["Palau", "PLW"],
+        "PY" => ["Paraguay", "PRY"],
+        "QA" => ["Qatar", "QAT"],
+        "RE" => ["Réunion", "REU"],
+        "RO" => ["Romania", "ROU"],
+        "RS" => ["Serbia", "SRB"],
+        "RU" => ["Russia", "RUS"],
+        "RW" => ["Rwanda", "RWA"],
+        "SA" => ["Saudi Arabia", "SAU"],
+        "SB" => ["Solomon Islands", "SLB"],
+        "SC" => ["Seychelles", "SYC"],
+        "SD" => ["Sudan", "SDN"],
+        "SE" => ["Sweden", "SWE"],
+        "SG" => ["Singapore", "SGP"],
+        "SH" => ["Saint Helena", "SHN"],
+        "SI" => ["Slovenia", "SVN"],
+        "SJ" => ["Svalbard and Jan Mayen", "SJM"],
+        "SK" => ["Slovakia", "SVK"],
+        "SL" => ["Sierra Leone", "SLE"],
+        "SM" => ["San Marino", "SMR"],
+        "SN" => ["Senegal", "SEN"],
+        "SO" => ["Somalia", "SOM"],
+        "SR" => ["Suriname", "SUR"],
+        "SS" => ["South Sudan", "SSD"],
+        "ST" => ["São Tomé and Príncipe", "STP"],
+        "SV" => ["El Salvador", "SLV"],
+        "SX" => ["Sint Maarten", "SXM"],
+        "SY" => ["Syria", "SYR"],
+        "SZ" => ["Eswatini", "SWZ"],
+        "TC" => ["Turks and Caicos Islands", "TCA"],
+        "TD" => ["Chad", "TCD"],
+        "TF" => ["French Southern Territories", "ATF"],
+        "TG" => ["Togo", "TGO"],
+        "TH" => ["Thailand", "THA"],
+        "TJ" => ["Tajikistan", "TJK"],
+        "TK" => ["Tokelau", "TKL"],
+        "TL" => ["Timor-Leste", "TLS"],
+        "TM" => ["Turkmenistan", "TKM"],
+        "TN" => ["Tunisia", "TUN"],
+        "TO" => ["Tonga", "TON"],
+        "TR" => ["Turkey", "TUR"],
+        "TT" => ["Trinidad and Tobago", "TTO"],
+        "TV" => ["Tuvalu", "TUV"],
+        "TW" => ["Taiwan", "TWN"],
+        "TZ" => ["Tanzania", "TZA"],
+        "UA" => ["Ukraine", "UKR"],
+        "UG" => ["Uganda", "UGA"],
+        "UM" => ["United States Minor Outlying Islands", "UMI"],
+        "US" => ["United States", "USA"],
+        "UY" => ["Uruguay", "URY"],
+        "UZ" => ["Uzbekistan", "UZB"],
+        "VA" => ["Vatican City", "VAT"],
+        "VC" => ["Saint Vincent and the Grenadines", "VCT"],
+        "VE" => ["Venezuela", "VEN"],
+        "VG" => ["British Virgin Islands", "VGB"],
+        "VI" => ["U.S. Virgin Islands", "VIR"],
+        "VN" => ["Vietnam", "VNM"],
+        "VU" => ["Vanuatu", "VUT"],
+        "WF" => ["Wallis and Futuna", "WLF"],
+        "WS" => ["Samoa", "WSM"],
+        "YE" => ["Yemen", "YEM"],
+        "YT" => ["Mayotte", "MYT"],
+        "ZA" => ["South Africa", "ZAF"],
+        "ZM" => ["Zambia", "ZMB"],
+        "ZW" => ["Zimbabwe", "ZWE"]
+      }.freeze
+      # rubocop:enable Style/WordArray
+
+      # ISO 3166-1 alpha-2 country codes (derived from COUNTRY_DATA).
+      ISO_COUNTRY_CODES = Set.new(COUNTRY_DATA.keys).freeze
+
+      # Downcased English country name => alpha-2, and alpha-3 => alpha-2.
+      NAME_TO_ALPHA2 = COUNTRY_DATA.to_h { |code, (name, _a3)| [name.downcase, code] }.freeze
+      ALPHA3_TO_ALPHA2 = COUNTRY_DATA.to_h { |code, (_name, a3)| [a3, code] }.freeze
 
       # Per-country postal-code patterns (matched against the *normalized*,
       # upcased value). `:default` is a permissive fallback for everything else.
@@ -97,6 +333,23 @@ module ConcernsOnRails
         compact = normalized.delete(" ")
         compact.match?(/\A[A-Z]\d[A-Z]\d[A-Z]\d\z/) ? "#{compact[0, 3]} #{compact[3, 3]}" : normalized
       end
+
+      # Canonicalize a country value to its ISO 3166-1 alpha-2 code: an existing
+      # alpha-2 is upcased; a 3-letter alpha-3 (e.g. "USA") and a recognized
+      # English name (e.g. "Canada") map to the alpha-2. Unrecognized values are
+      # returned unchanged, and non-strings pass through.
+      def normalize_country_code(value)
+        return value unless value.is_a?(String)
+
+        trimmed = value.strip.squish
+        return value if trimmed.empty?
+
+        upper = trimmed.upcase
+        return upper if ISO_COUNTRY_CODES.include?(upper)
+        return ALPHA3_TO_ALPHA2[upper] if ALPHA3_TO_ALPHA2.key?(upper)
+
+        NAME_TO_ALPHA2[trimmed.downcase] || value
+      end
     end
   end
 end

data/lib/concerns_on_rails/version.rb

@@ -1,3 +1,3 @@
 module ConcernsOnRails
-  VERSION = "1.11.0".freeze
+  VERSION = "1.11.2".freeze
 end

data/lib/concerns_on_rails.rb

@@ -28,6 +28,7 @@ require "concerns_on_rails/models/tokenizable"
 require "concerns_on_rails/models/stateable"
 require "concerns_on_rails/models/addressable"
 require "concerns_on_rails/models/sequenceable"
+require "concerns_on_rails/models/taggable"
 
 # Controller concerns
 require "concerns_on_rails/controllers/paginatable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concerns_on_rails
 version: !ruby/object:Gem::Version
-  version: 1.11.0
+  version: 1.11.2
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -90,6 +90,7 @@ files:
 - lib/concerns_on_rails/models/soft_deletable.rb
 - lib/concerns_on_rails/models/sortable.rb
 - lib/concerns_on_rails/models/stateable.rb
+- lib/concerns_on_rails/models/taggable.rb
 - lib/concerns_on_rails/models/tokenizable.rb
 - lib/concerns_on_rails/support/address_data.rb
 - lib/concerns_on_rails/support/column_guard.rb