usernames 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec486faa743e1c58387d30c1cac821ff0365b4aba93599c646eceb153706394
-  data.tar.gz: 45a21a2e40e4245a6e3304fe6ef7e74f365f1270a40fc6c79a9dab06f6a14f2f
+  metadata.gz: 0ec6362d06fa7d1d326142514846d8bff7919e3fd6a2d7987819c7d6161b29f2
+  data.tar.gz: ce53042c9f1116fa5e98bdf46291c0f212d2b9aa27ad4455c7ba055169cf8764
 SHA512:
-  metadata.gz: 04e01ab2a747c93ca4f03419a8551becaf01cf4d3a624246f78e09d3511ce05a5fe42095a7617c62439885e5fabcdc5f7a760519d5683d71d1e82b7110a981f2
-  data.tar.gz: 7c732ebc8d69dda5e97f8f6267e118159e5d7a06827868ec6835bdb412580c50abac0c04e3ceb02892f4968734d83c99fec7cc5d47f4a4981561d67ad9af1429
+  metadata.gz: 74ed5ba9b1994027c8fbabc46dd2fe40871482dfce974df4082ca8029c15a33af1a83850f7bd6470443a0e33d0e2dd8081b7e94f8d817628906955e7b74f478c
+  data.tar.gz: 0ed17f0406d8eff7d2155865010bec6d60dba7ff3b7ef0e97526e8e7d27317eae47a6fe36d64518f2e856dff57bdb7f43ee49c7f8726468e8ae2a1e7104fd4d7

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-27
+
+The live availability check moves into the gem. In 0.1 it was a generator that copied a controller, a route, a Stimulus controller and a partial into every app, each yours to keep in step with the gem; now the engine ships all of it, and in an app on the conventional importmap + Stimulus setup a username field that checks names as people type is four lines: `gem "usernames"`, `has_username :handle`, `<%= f.username_field :handle %> <%= f.username_status :handle %>` and `import "usernames"` — with no copied username implementation left in the app. `has_username` also learns three options that apps were writing by hand around it.
+
+### Added
+
+- **The availability endpoint**, `Usernames::AvailabilityController`, at `GET /usernames/availability?username=…&target=…`, answering `{ state: "free" | "taken" | "invalid", message: }` in the model's own words. The guard rails of the 0.1 template come with it: Rails' `rate_limit` (`config.availability.rate_limit`, on a counter of its own, apart from any limiter the parent controller declares), taken, reserved and disallowed names answered alike as "taken", the server's own normaliser first, and `Cache-Control: no-store` on every answer — 404s, 429s and 503s included.
+- **Targets: an explicit allowlist** of what the endpoint answers for, `config.availability.targets = { "user" => "User#handle" }`, which the installer writes. A request names an alias; only a configured alias is looked up, and the class it names is resolved from your configuration on every request — never from what a client sent — so declaring `has_username` on a model never publishes it. An unknown alias is a 404 (rate limited like any request); a configured one that no longer resolves raises `Usernames::ConfigurationError` instead of answering.
+- **A route drawn by the engine**, appended after yours as `usernames_availability` at `config.availability.path` (`nil` draws none), without a format, and skipped when you draw one of that name yourself. `usernames_availability` is also a routing method, for putting it above a catch-all such as `get "*path"`, which would otherwise swallow it. Its first segment is reserved like any of your routes.
+- **Form helpers.** `f.username_field :handle` renders the input with the `username-check` controller on it — the rules (messages in the model's words), the case mode, the saved name and the endpoint — and `f.username_status :handle` the `<output aria-live="polite">` it writes to. `availability: false` keeps the format hints without a request; `static: true` is a plain field. `class`, `data-controller`, `data-action` and `aria-describedby` join the field's own; ids follow `field_id`, namespaces and indexes included. A field for a column no target names raises in development and test, and renders plain (logged once) in production.
+- **JavaScript shipped by the gem**, in `app/assets/javascripts/usernames/`: the Stimulus controller, and `index.js`, which registers it on stimulus-rails' exported `application` — deterministically, once. With importmap-rails the engine pins `usernames` and `usernames/username-check` (before importmap draws its map); Propshaft and Sprockets serve both files, and Sprockets is told to precompile them. Without importmap-rails, or without an asset pipeline, the engine adds nothing. The controller shows `checking`, `free`, `taken`, `invalid`, `unchanged` or `error` in the status's `data-state`; a request generation counter and aborts make sure only the latest answer is shown (A, then B, then A again included), a 429, 503, network failure, unreadable answer or no answer within the `timeout` value (8 seconds, headers and body together) ends in `error` with a localised message (`usernames.availability.error`, in English, Spanish and Portuguese), and the status resets on disconnect, on form reset and before Turbo caches the page. It still never blocks submission.
+- **`config.reserved_if`**: a callable asked last, after every word list, about the name as normalised — `->(name) { Page.exists?(slug: name) }` — so names your data reserves (page slugs, organisations) are refused as `is reserved`, everywhere a reserved name is. `nil` by default, checked at boot to answer `call`, also accepted per model; `config.allowed` still lifts it, and `rails usernames:reserved` mentions it.
+- **`required: { on: :profile }`** asks for a name whenever the record is validated in that context (or one of several), on every save there — including an account whose name was blank before the gem arrived, since that form is where they type one. Outside it, nothing changes.
+- **`seed: :first_name`** (or a proc): a generated name starts from that value — `ana`, then `ana_42`, then the default shape when it is blank or every form of it is taken. It is read once per save and reused by a redraw after a lost race; an error raised in it is the app's.
+- **`clearable: false`** refuses saving a saved name blank again (`:blank`), required or not. It is not immutability, leaves stored blanks alone, and — being a validation — is skipped by `update_column` and `update_all`.
+- **`config.availability.parent_controller`** (default: your `ApplicationController` when there is one, so its locale and authentication callbacks apply; `"ActionController::API"` works) and **`config.availability.rate_limit_store`** (default `Rails.cache`, read once when the endpoint's class loads).
+- **`rails generate usernames:javascript`** copies the Stimulus controller into `app/javascript/controllers` for apps that bundle their JavaScript, where `import "usernames"` has nothing to resolve it.
+
+### Changed
+
+- **`rails generate usernames:install`** writes `config.availability.targets` for its `--model`/`--column`, and in an importmap app whose `controllers/application.js` exports the Stimulus application it appends `import "usernames"` to `app/javascript/application.js` — once, never removing anything — saying why not otherwise. It ends with the form line, the production cache store and — when Devise is loaded — the two `devise_parameter_sanitizer.permit` lines that keep Devise from dropping the field.
+- **`rails generate usernames:availability`** no longer copies anything by default: it explains that the check is built in, and lists the files a 0.1 install copied, with the two ways to upgrade. `--copy` writes a set of your own — the endpoint (replacing the gem's, same class), the Stimulus controller, a partial built on the helpers, and the route at the top of `config/routes.rb` — all speaking the same protocol.
+- **A rate limit store that can't count is a 503 everywhere but development and test.** 0.1 answered 503 only in production and only for a `NullStore`; the endpoint now notices any store whose `increment` returns nothing or fails (a cache whose backend is down, a wrapper around a `NullStore`), and refuses in staging too. In development and test it proceeds unlimited and logs once.
+
+### Fixed
+
+- **A new record saved in a validation context of its own got no generated name.** Generation ran `on: :create`, which an explicit context (`save(context: :import)`) replaces, so such records were saved without one. It now runs for every new record whose name is blank, whatever the context.
+
+### Upgrading from 0.1
+
+Nothing changes for a model with `has_username` and no availability check. If you ran `rails generate usernames:availability` under 0.1:
+
+- **Your copied files speak the 0.1 protocol, and they win over the gem's.** Your controller reads `params[:<column>]` and asks `current_user`; the gem's helpers send `username` and `target`. Pick one mode — `rails generate usernames:availability` lists what it finds. *Managed* (recommended): delete the controller, the `usernames/availability` route, `app/javascript/controllers/username_check_controller.js` and `app/views/usernames/_field.html.erb`; add `config.availability.targets = { "user" => "User#username" }`, replace the partial with `f.username_field` / `f.username_status`, and add `import "usernames"`. *Customized*: keep your pair, set `config.availability.path = nil`, and don't `import "usernames"` (both would register `username-check`).
+- **"Already your name" is the browser's call now.** The endpoint no longer asks who is signed in: the field carries the record's saved name and shows `unchanged` without asking. A server-side `current_user` check in a copied controller is yours to keep or drop.
+- **Staging needs a cache store that counts.** See *Changed*: a `NullStore` there now turns the endpoint off (503) rather than letting it run unlimited.
+- **Devise drops fields it doesn't know.** If people choose their name at sign-up, permit it: `devise_parameter_sanitizer.permit(:sign_up, keys: [:handle])` and `:account_update`.
+- **New locale key** `usernames.availability.error` ("couldn't be checked just now"; Spanish and Portuguese ship). In a language the gem doesn't ship, it and `usernames.available` read in English — your app's own English wording, if it has one, else the gem's, even in an app whose available locales leave English out — until you add them to that language's locale file. They never read "Translation missing", with or without I18n fallbacks.
+- **A new record saved with a custom validation context now gets a generated name** (see *Fixed*). If you relied on it staying blank, pass `generate: false` or a condition.
+- `clearable:` defaults to `true`: names can still be cleared, as in 0.1. Pass `clearable: false` to stop that.
+
 ## [0.1.3] - 2026-10-27
 
 ### Changed

data/README.md

@@ -60,7 +60,7 @@ rails generate usernames:install
 rails db:migrate
 ```
 
-The generator writes `config/initializers/usernames.rb` (ten options, all commented), adds a `username` column to `users` if there isn't one, and adds **the one unique index the gem needs** — with the right collation, so the database agrees with Ruby about what "the same name" means (see [Uniqueness, case and collation](#uniqueness-case-and-collation)).
+The generator writes `config/initializers/usernames.rb` (ten options, all commented, and one live line that publishes the column to the [live availability check](#live-availability-check)), adds a `username` column to `users` if there isn't one, and adds **the one unique index the gem needs** — with the right collation, so the database agrees with Ruby about what "the same name" means (see [Uniqueness, case and collation](#uniqueness-case-and-collation)).
 
 Then, in your model:
 
@@ -81,6 +81,24 @@ end
 > [!IMPORTANT]
 > **Already have users?** `has_username` only checks a username **when it changes**, so adding the gem never stops an existing account from saving its other attributes. But Rails' `normalizes` doesn't rewrite rows already in the database, and a stored `JAVI` next to a new `javi` would be two identities. Run `rails usernames:audit` first and read [Adopting an existing column](#adopting-an-existing-column) — it's a five-minute, read-only check.
 
+## Quickstart: a username field in four lines
+
+Once the column is installed and migrated (and audited, if it already held names), this is the whole integration for a `User` with a `handle`, in an app on the conventional importmap + Stimulus setup:
+
+```text
+gem "usernames"                                                                        # Gemfile
+has_username :handle, case: :preserve                                                  # app/models/user.rb
+<%= f.label :handle %> <%= f.username_field :handle %> <%= f.username_status :handle %>   # any form for a User
+import "usernames"                                                                     // app/javascript/application.js
+```
+
+(`rails generate usernames:install --column=handle --case=preserve` writes the migration, adds the `import` line, and publishes `User#handle` to the live check in the initializer.)
+
+As someone types, the field shows the first format rule the name breaks — the same rules and the same words as the server, with no round trip — then, once typing pauses, whether the name is free. Their own saved name is simply *unchanged*. Nothing in the browser blocks submission: the model and its unique index decide.
+
+No copied username implementation lives in your app: the endpoint, its route, the Stimulus controller and the form helpers are the gem's, and upgrade with it. What stays yours is what is genuinely about your app — your forms, your labels and styling, and, with Devise, the one line that permits the field (see [With Devise](#with-devise)). Not on importmap, or no Stimulus? See [How it is wired](#how-it-is-wired-and-how-to-turn-each-piece-off).
+
+
 ## What it checks, in order
 
 The first failing rule names the error. Messages never contain what the user typed, so they can never echo abuse back or trip I18n on a `%{` someone pasted.
@@ -129,6 +147,18 @@ end
 | 2 | `config.reserved`, `config.forbidden` | reserved |
 | 3 | your routes | reserved |
 | 4 | the bundled lists | reserved |
+| 5 | `config.reserved_if` | reserved |
+
+**Names your data reserves.** A slug your pages already use, a team or an organisation that shares the URL space — anything that isn't a fixed list — is one callable, asked last, only about names every list has let through:
+
+```ruby
+Usernames.configure do |config|
+  config.reserved_if = ->(name) { Page.exists?(slug: name) || Organization.exists?(handle: name) }
+end
+```
+
+It receives the name as normalised (lowercased in the default mode, case kept with `case: :preserve`), and a truthy answer refuses it as `is reserved` — in validation, in `Usernames.check`, and as "taken" in the availability check. `config.allowed` still lifts it. What it raises is your app's error, not the gem's; it runs on every check that reaches it, so keep it to one indexed query.
+
 
 Your own official account, under a name the gem reserves? Lift exactly that name — `config.allowed += %w[yourapp]` — and register it yourself before launch (a seed, or the console). It frees that exact name only: `yourapp2` and `your.app` stay reserved. `has_username` deliberately has no per-record skip: whether a name may be held is a fact about the name, and a skip that hangs off the record is one `update` away from letting someone else keep `admin`. `rails usernames:reserved` prints the effective list with the source of every word, for when you wonder why `x` is reserved.
 
@@ -190,7 +220,7 @@ Alternatively, `case: :preserve` leaves stored case alone; the audit will tell y
 
 ## Generated names and suggestions
 
-Every new account has a name from day one. A profile with no name is a row that renders as plain text everywhere and has no page — so `has_username` assigns one on create when the field is blank. (Only on create: an existing account may still clear its username, unless you pass `required: true`.)
+Every new account has a name from day one. A profile with no name is a row that renders as plain text everywhere and has no page — so `has_username` assigns one to a new record whose field is blank, whatever validation context it is saved in. (Only to new records: an existing account may still clear its username, unless you pass `required: true` or `clearable: false`.)
 
 ```ruby
 User.create!(email: "ana@example.com").username   # => "quiet_otter_42"
@@ -207,6 +237,32 @@ has_username required: -> { invited? }, generate: false
 
 By default a name is generated exactly where none is required, record by record. An explicit `generate:` is honoured as given: `required: true, generate: true` fills a blank on create and refuses clearing it later.
 
+A profile form that asks for the name, while sign-up hands one out? Require it in that validation context only:
+
+```ruby
+has_username required: { on: :profile }     # or { on: %i[profile onboarding] }
+```
+
+```ruby
+.save(context: :profile)               # in the profile controller: the name can't be blank here
+```
+
+Presence is then checked on every save in that context — even for an account whose name was blank before the gem arrived, since that form is where they type one. Every other save works as without it. The context has to come from your controller: a form can't set it.
+
+**Keeping a name.** `clearable: false` refuses saving a saved name blank again (`can't be blank`), required or not — a username other people link to stays one. It is not immutability: changing it to another name is fine. A stored blank was never a name, so it saves as before, and `update_column` / `update_all` skip it like any validation.
+
+```ruby
+has_username clearable: false
+```
+
+**Starting from the person's name.** `seed:` names a method (or a proc) whose value a generated name starts from:
+
+```ruby
+has_username seed: :first_name     # Ana → "ana", or "ana_42" if taken, or "quiet_otter_42" when first_name is blank
+```
+
+It is read once per save, cleaned and cut at word boundaries the way `generate_username(from:)` does it below; a redraw after a lost race reuses it, and an error raised in it is your app's. Whatever it returns becomes part of a **public** name: `seed: :email` publishes the local part of people's addresses (`ana+news.com` → `ana`), which is exactly what the gem never does on its own.
+
 From a real name:
 
 ```ruby
@@ -240,13 +296,104 @@ Whatever you return still goes through the validator and the redraw logic.
 
 ## Live availability check
 
+```erb
+<%= form_with model: @user do |f| %>
+  <%= f.label :handle %>
+  <%= f.username_field :handle %>
+  <%= f.username_status :handle %>
+<% end %>
+```
+
+`f.username_field` is a text field (`autocomplete="username"`, no autocapitalise or autocorrect — pass any option to change them) that the gem's `username-check` Stimulus controller watches. `f.username_status` is the `<output for="user_handle" aria-live="polite">` it writes to, so screen readers hear the answer too. The status gets a `data-state` to style: `checking`, `free`, `taken`, `invalid` (a format rule, said at once, in the model's own words), `unchanged` (the record's saved name, typed again in any case — not asked about), or `error` (the answer didn't come: offline, rate limited, switched off, or not within eight seconds). Nothing blocks submission: no `pattern`, no `setCustomValidity`, no `maxlength` (it would cut a pasted `@name` before normalisation; pass `maxlength:` if you want one).
+
+```erb
+<%= f.username_field :handle, availability: false %>   <%# format hints only, no request %>
+<%= f.username_field :handle, static: true %>          <%# a plain text field %>
+<%= f.username_field :handle, class: "input", data: { controller: "autosize" } %>   <%# joined, not replaced %>
+```
+
+`class`, `data-controller`, `data-action` and `aria-describedby` are joined with the field's own; ids come from `field_id` (`user_handle`, `user_handle_status`), so `namespace:` and `index:` work. Two forms for the same record on one page need different ids: give `form_with` a `namespace:`, or pass the same `id:` to both helpers.
+
+The browser asks `GET /usernames/availability?username=javi&target=user` and gets `{ "state": "free" | "taken" | "invalid", "message": "…" }`. `target` is an alias from `config.availability.targets`, which the installer writes:
+
+```ruby
+config.availability.targets = { "user" => "User#handle" }      # alias => "Model#column"
+```
+
+Only these are ever answered: anything else is a 404, and declaring `has_username` on a model never publishes it. A field for a column that isn't a target raises in development and test (and renders as a plain field, with one log line, in production). A single-table subclass's form uses its parent's target.
+
+An availability endpoint tells anyone which names exist — that is its job — so it comes with guard rails:
+
+- **Rate limited** with Rails' `rate_limit` (30 a minute per IP), counted in `Rails.cache`, on a counter of its own: a limiter your `ApplicationController` declares counts separately. If that store can't count — the `NullStore`, or a backend that's down — Rails' limiter silently lets everything through, so outside development and test the endpoint answers **503**, with a log line, until it can. In production that means a shared store: Solid Cache, Redis or Memcached. (A `MemoryStore` works, per process, with a warning.)
+- **Uniform answers**: taken, reserved and disallowed names all answer "taken". No word list, matched word or reason is sent to the browser — though, like any availability check, it can't stop someone inferring a list by asking.
+- **Never cached** (`Cache-Control: no-store`), 404s, 429s and 503s included, and advisory only: the model's validations and the unique index decide at save time.
+- **Public by default.** It inherits your `ApplicationController` (when there is one), so its locale, host and authentication callbacks apply — the messages come in the language your app picked. It knows nothing about who is signed in; "unchanged" is the browser comparing against the saved name the field carries.
+
+### How it is wired (and how to turn each piece off)
+
+| Piece | What the gem does | Off switch |
+|---|---|---|
+| Endpoint | `Usernames::AvailabilityController`, inheriting `config.availability.parent_controller` (default: `ApplicationController` if defined, else `ActionController::Base`; `"ActionController::API"` works) | `config.availability.targets = {}` answers nothing |
+| Route | appended after your routes, named `usernames_availability`, at `config.availability.path` (`/usernames/availability`), no format. Its first segment (`usernames`) is reserved like any of your routes | `config.availability.path = nil`, or draw a route of that name yourself |
+| Rate limit | `config.availability.rate_limit = { to: 30, within: 1.minute }`, counted in `config.availability.rate_limit_store` (default `Rails.cache`, read once at boot) | — (point it at a store that counts) |
+| Form helpers | `f.username_field` / `f.username_status` on every form builder | `availability: false`, `static: true`, or don't use them |
+| JavaScript | with importmap-rails, the pins `usernames` and `usernames/username-check`; Propshaft and Sprockets serve them | leave out `import "usernames"` |
+
+`import "usernames"` imports your `controllers/application` (stimulus-rails' generated file, which exports `application`) and registers `username-check` on it, once. Starting Stimulus some other way? Import the controller alone and register it yourself:
+
+```js
+import UsernameCheckController from "usernames/username-check"
+application.register("username-check", UsernameCheckController)
+```
+
+**Catch-all routes.** The appended route comes after yours, so a catch-all such as `get "*path"` swallows it. Put it above the catch-all yourself, and the gem draws nothing more:
+
+```ruby
+Rails.application.routes.draw do
+  usernames_availability                    # at the top level, before any catch-all
+  get "*path", to: "pages#show"
+end
+```
+
+**No Stimulus** (or JavaScript off): the field is an ordinary text field, and the model still says why a name won't do on submit.
+
+**jsbundling, esbuild, Vite…** `import "usernames"` needs importmap. Copy the controller instead, and register it as `username-check`:
+
 ```bash
-rails generate usernames:availability
+rails generate usernames:javascript      # app/javascript/controllers/username_check_controller.js
+```
+
+The copy is then your app's: run the generator again after upgrading the gem.
+
+**Customising the endpoint or the controller**: `rails generate usernames:availability --copy` writes the endpoint (it replaces the gem's — same class), the Stimulus controller, a form partial and the route into your app, all speaking the same protocol. Drop `import "usernames"` then: your Stimulus setup registers your copy.
+
+### With Devise
+
+Devise permits only its own attributes, so a `handle` field it doesn't know about is dropped — the form says the name is free, the save ignores it, and the account gets a generated one. Permit it where people choose or change it:
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :configure_permitted_parameters, if: :devise_controller?
+
+  private
+
+  def configure_permitted_parameters
+    devise_parameter_sanitizer.permit(:sign_up, keys: [:handle])
+    devise_parameter_sanitizer.permit(:account_update, keys: [:handle])
+  end
+end
 ```
 
-Copies into **your** app — nothing is mounted behind your back — a small controller, a route (`GET /usernames/availability?username=…`), a Stimulus controller and a form partial. As people type, the browser shows the format rules instantly (same rules, same words as the server, no round trip) and asks the server whether the name is free, debounced, with stale answers discarded. Browser hints never block submission; the server is the only authority.
+That's strong parameters, which are your app's decision: the gem never mass-assigns anything. Logging in with a username or an email is a recipe [below](#recipes).
+
+### Upgrading from 0.1
+
+0.1's `rails generate usernames:availability` copied a controller, a `usernames/availability` route, a Stimulus controller and a `_field` partial into your app. They speak the 0.1 protocol, and your app's copies win over the gem's, so pick one mode (`rails generate usernames:availability` lists what it finds):
+
+- **Managed** (recommended): delete all four, add `config.availability.targets = { "user" => "User#username" }` to the initializer, replace the partial with `f.username_field` / `f.username_status`, and add `import "usernames"`. From then on the check upgrades with the gem.
+- **Customized**: keep your pair, set `config.availability.path = nil` so the gem draws no route of its own (yours is named `usernames_availability`, so it would skip anyway), and don't `import "usernames"`.
 
-An availability endpoint reveals which names exist by design, so the generated controller comes with guard rails: it rate-limits with Rails' built-in `rate_limit`, it refuses to run (503, with a log line) if your cache store is the `NullStore` — Rails' limiter silently does nothing there — and it answers "taken" for taken, reserved and disallowed names alike. The word lists never reach the browser.
+The rest of 0.2.0 is listed in the [CHANGELOG](CHANGELOG.md#upgrading-from-01).
 
 ## Recipes
 
@@ -313,7 +460,7 @@ es:
               username_reserved: "está reservado"
 ```
 
-A per-model override reaches every place the gem speaks for that model: `User.check_username(value)` (`Usernames.check` with the model's rules and words) and `User.username_rules_for_browser` (the hints) look messages up the way the model's own errors do, and the generated availability check uses both, so the form, the hints and the endpoint say the same thing.
+A per-model override reaches every place the gem speaks for that model: `User.check_username(value)` (`Usernames.check` with the model's rules and words) and `User.username_rules_for_browser` (the hints) look messages up the way the model's own errors do, and the availability check uses both, so the form, the hints and the endpoint say the same thing. Its own two messages are `usernames.available` ("is available") and `usernames.availability.error` ("couldn't be checked just now").
 
 `rails generate usernames:locale --locale=fr` copies the English file for you to translate.
 
@@ -338,7 +485,7 @@ Usernames.configure do |config|
 end
 ```
 
-Less common, documented here rather than in the initializer: `first_character` (`:alphanumeric`, or `:letter` for the Snapchat/Telegram rule), `reserve_routes` (`true`), `app_name` (auto-detected; `false` to opt out), `offensive.adapters` (`[:moderate]`), `on_adapter_failure` (`:allow` logs and skips a raising adapter; `:reject` fails the save), `generator.adjectives` / `generator.nouns` / `generator` (a callable), `unique_index` (only if the generator didn't create yours). Every option is also accepted per model — `has_username :handle, length: 2..24` — and per validator call. `has_username` itself takes `required:` (`false`; `true`, a method name such as `required: :handle_required`, or a proc) and `generate:` (by default: wherever a name isn't required). An invalid value raises `Usernames::ConfigurationError` at boot, naming it.
+Less common, documented here rather than in the initializer: `first_character` (`:alphanumeric`, or `:letter` for the Snapchat/Telegram rule), `reserve_routes` (`true`), `app_name` (auto-detected; `false` to opt out), `offensive.adapters` (`[:moderate]`), `on_adapter_failure` (`:allow` logs and skips a raising adapter; `:reject` fails the save), `generator.adjectives` / `generator.nouns` / `generator` (a callable), `unique_index` (only if the generator didn't create yours), `reserved_if` (`nil`; a callable, see [Reserved names](#reserved-names)). Every option is also accepted per model — `has_username :handle, length: 2..24` — and per validator call. `has_username` itself takes `required:` (`false`; `true`, a method name such as `required: :handle_required`, a proc, or `{ on: :profile }`), `generate:` (by default: wherever a name isn't required), `seed:` (a method name or a proc) and `clearable:` (`true`). The availability check reads `config.availability.targets` (`{}` until the installer writes yours), `.path` (`"/usernames/availability"`, `nil` for no route), `.parent_controller` (`nil`: your `ApplicationController`, else `ActionController::Base`), `.rate_limit` (`{ to: 30, within: 1.minute }`) and `.rate_limit_store` (`nil`: `Rails.cache`). An invalid value raises `Usernames::ConfigurationError` at boot, naming it.
 
 ## Data and licences
 

data/app/assets/javascripts/usernames/index.js

@@ -0,0 +1,16 @@
+// import "usernames" — in app/javascript/application.js, for the conventional
+// importmap + Stimulus setup (stimulus-rails' controllers/application.js,
+// which exports `application`). Registers the username-check controller on
+// that application, once, after it exists: the import below orders it.
+//
+// An app that starts Stimulus some other way skips this file and registers
+// the controller itself:
+//
+//   import UsernameCheckController from "usernames/username-check"
+//   application.register("username-check", UsernameCheckController)
+import { application } from "controllers/application"
+import UsernameCheckController from "usernames/username-check"
+
+application.register("username-check", UsernameCheckController)
+
+export { UsernameCheckController }

data/app/assets/javascripts/usernames/username_check_controller.js

@@ -0,0 +1,191 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Live hints and an "is this name free?" check on a username field, from the
+// usernames gem. `f.username_field :handle` puts it on the input itself;
+// `f.username_status :handle` renders the <output> it writes to:
+//
+//   <input data-controller="username-check" data-action="input->username-check#check"
+//          data-username-check-url-value="/usernames/availability"
+//          data-username-check-target-value="user"
+//          data-username-check-rules-value="[…User.handle_rules_for_browser…]"
+//          data-username-check-status-id-value="user_handle_status"
+//          aria-describedby="user_handle_status">
+//   <output id="user_handle_status" for="user_handle" aria-live="polite"></output>
+//
+// The status gets a data-state for styling: checking, free, taken, invalid,
+// unchanged (the record's saved name, so nothing to ask), error (the answer
+// didn't come: offline, rate limited, switched off) or "" (nothing to say).
+//
+// Everything here is a HINT. The browser only approximates the server's
+// normalisation (Ruby's strip and JavaScript's trim() disagree on NUL, U+FEFF
+// and U+1680), so nothing here blocks submission: no setCustomValidity, no
+// pattern attribute. The model's validations and the unique index decide.
+export default class extends Controller {
+  static values = {
+    // GET <url>?username=<typed>&target=<target>; no url, no request (format hints only).
+    url: String,
+    target: String,
+    rules: Array,
+    lowercase: { type: Boolean, default: true },
+    persisted: String,
+    statusId: String,
+    errorMessage: String,
+    delay: { type: Number, default: 300 },
+    // How long an answer may take, headers and body together, before it is an error.
+    timeout: { type: Number, default: 8000 }
+  }
+
+  connect() {
+    this.patterns = this.rulesValue.map((rule) => ({ ...rule, regexp: this.compile(rule.pattern) }))
+    this.generation = 0
+    this.reset = this.reset.bind(this)
+    this.form = this.element.form
+    if (this.form) this.form.addEventListener("reset", this.reset)
+    document.addEventListener("turbo:before-cache", this.reset)
+  }
+
+  disconnect() {
+    this.reset()
+    if (this.form) this.form.removeEventListener("reset", this.reset)
+    document.removeEventListener("turbo:before-cache", this.reset)
+  }
+
+  // On every keystroke: the saved name is simply unchanged; otherwise the
+  // first rule the name breaks, at once, and whether it is free once
+  // typing pauses. Every call starts a new generation: an answer for an
+  // older one is never shown, even for the same name typed again (A, B, A).
+  check() {
+    const typed = this.element.value
+    const generation = ++this.generation
+    this.cancel()
+
+    if (this.unchanged(typed)) return this.render({ state: "unchanged", message: "" })
+
+    const name = this.normalize(typed)
+    const broken = this.firstBrokenRule(name)
+    if (broken) return this.render({ state: "invalid", message: broken.message })
+    // Only names that could be registered are worth a request.
+    if (name === "" || !this.urlValue) return this.render(null)
+
+    this.render({ state: "checking", message: "" })
+    this.timer = setTimeout(() => this.ask(name, generation), this.delayValue)
+  }
+
+  async ask(name, generation) {
+    const request = new AbortController()
+    this.request = request
+    const url = new URL(this.urlValue, window.location.href)
+    url.searchParams.set("username", name)
+    if (this.targetValue) url.searchParams.set("target", this.targetValue)
+
+    // The deadline covers the headers and the body alike: a stalled
+    // connection, or a body that never finishes, ends in "error" too.
+    // Aborting rejects `abandoned`, so neither await can outlive it.
+    let timedOut = false
+    const abandoned = new Promise((_resolve, reject) => {
+      request.signal.addEventListener("abort", () => reject(new DOMException("Aborted", "AbortError")), { once: true })
+    })
+    abandoned.catch(() => {})
+    const deadline = setTimeout(() => {
+      timedOut = true
+      request.abort()
+    }, this.timeoutValue)
+    this.deadline = deadline
+
+    let answer = null
+    try {
+      const response = await Promise.race([fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: request.signal,
+        credentials: "same-origin"
+      }), abandoned])
+      if (response.ok) answer = await Promise.race([response.json(), abandoned])
+    } catch (error) {
+      // Cancelled because a newer check took over, or by a reset: say
+      // nothing. Out of time is an answer of its own, below.
+      if (error.name === "AbortError" && !timedOut) return
+    } finally {
+      clearTimeout(deadline)
+    }
+    // A slow answer for something typed earlier is not an answer for this.
+    if (generation !== this.generation) return
+
+    this.request = null
+    // 429, 503, a network failure, no answer in time or something unreadable:
+    // say so, never "checking" forever.
+    this.render(this.understood(answer) ? answer : { state: "error", message: this.errorMessageValue })
+  }
+
+  // Forgets whatever is in flight and clears the status: on disconnect, when
+  // the form is reset, and before Turbo caches the page.
+  reset() {
+    this.cancel()
+    this.generation += 1
+    this.render(null)
+  }
+
+  // The record's saved name, typed again (in any case, with or without a
+  // leading @): the server would only say it is taken — by its owner.
+  unchanged(typed) {
+    return this.persistedValue !== "" && this.fold(typed) === this.fold(this.persistedValue)
+  }
+
+  // How the server compares two names, approximately: NFKC, trimmed, one
+  // leading @ dropped, case ignored (in both case modes).
+  fold(value) {
+    return value.normalize("NFKC").trim().replace(/^@/, "").toLowerCase()
+  }
+
+  // The server's normalisation, approximately: NFKC, trim,
+  // lowercase (unless case is kept), one leading @ before a letter or digit.
+  normalize(value) {
+    let name = value.normalize("NFKC").trim()
+    if (this.lowercaseValue) name = name.toLowerCase().normalize("NFKC")
+    return name.replace(this.lowercaseValue ? /^@(?=[a-z0-9])/ : /^@(?=[A-Za-z0-9])/, "")
+  }
+
+  // Each pattern matches a name that BREAKS its rule; the first one wins.
+  firstBrokenRule(name) {
+    if (name === "") return null
+    return this.patterns.find(({ regexp }) => regexp && regexp.test(name)) || null
+  }
+
+  // With the u flag a length counts code points, as Ruby does.
+  compile(pattern) {
+    try {
+      return new RegExp(pattern, "u")
+    } catch {
+      try { return new RegExp(pattern) } catch { return null }
+    }
+  }
+
+  understood(answer) {
+    return answer !== null && typeof answer === "object" && ["free", "taken", "invalid"].includes(answer.state) &&
+      typeof answer.message === "string"
+  }
+
+  // The <output> named by the status-id value, or by the input's aria-describedby.
+  get status() {
+    const ids = [this.statusIdValue, ...(this.element.getAttribute("aria-describedby") || "").split(/\s+/)]
+    for (const id of ids) {
+      const element = id && document.getElementById(id)
+      if (element && element.tagName === "OUTPUT") return element
+    }
+    return null
+  }
+
+  render(answer) {
+    const status = this.status
+    if (!status) return
+
+    status.dataset.state = answer ? answer.state : ""
+    status.textContent = answer && answer.message ? answer.message : ""
+  }
+
+  cancel() {
+    clearTimeout(this.timer)
+    clearTimeout(this.deadline)
+    if (this.request) this.request.abort()
+    this.request = null
+  }
+}