usernames 0.1.3 → 0.2.0

data/lib/generators/usernames/templates/availability/_field.html.erb.tt

@@ -1,7 +1,7 @@
 <%%# locals: (form:, attribute: :<%= column %>, label: nil) -%>
 <%%#
-  A username field with live hints and an availability check.
-  Generated by `rails generate usernames:availability`. It's yours: edit it.
+  A username field with live hints and the availability check.
+  Generated by `rails generate usernames:availability --copy`. It's yours: edit it.
 
   Render it inside a form, handing it the form builder:
 
@@ -10,16 +10,6 @@
   Hints are advisory: nothing here stops the form from submitting, and the
   model's validations have the last word.
 -%>
-<div data-controller="username-check"
-     data-username-check-url-value="<%%= usernames_availability_path %>"
-     data-username-check-param-value="<%= column %>"
-     data-username-check-rules-value="<%%= <%= model_name %>.<%= column %>_rules_for_browser.to_json %>"
-     data-username-check-lowercase-value="<%%= <%= model_name %>.<%= column %>_options[:case] != :preserve %>">
-  <%%= form.label attribute, label %>
-  <%%= form.text_field attribute,
-        autocomplete: "username", autocapitalize: "none", autocorrect: "off", spellcheck: false,
-        aria: { describedby: "#{form.field_id(attribute)}_hint #{form.field_id(attribute)}_status" },
-        data: { username_check_target: "input", action: "input->username-check#check" } %>
-  <p id="<%%= form.field_id(attribute) %>_hint" data-username-check-target="hint" aria-live="polite"></p>
-  <p id="<%%= form.field_id(attribute) %>_status" data-username-check-target="status" aria-live="polite"></p>
-</div>
+<%%= form.label attribute, label %>
+<%%= form.username_field attribute %>
+<%%= form.username_status attribute %>

data/lib/generators/usernames/templates/usernames.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
-# Every line below shows the default: uncomment one to change it.
+# Every commented line below shows the default: uncomment one to change it.
 # The README documents the less common options (first_character,
 # reserve_routes, app_name, offensive.adapters, on_adapter_failure, generator,
-# unique_index). Every option is also accepted per model:
+# unique_index, and the rest of config.availability). Every rule is also
+# accepted per model:
 #   has_username :handle, length: 2..24, case: :preserve
 Usernames.configure do |config|
+  # The username columns the live availability check answers for, by the
+  # alias the browser sends (`f.username_field` fills it in). Nothing else is
+  # ever looked up: a model with has_username is not public until it is here.
+  config.availability.targets = { <%= target_alias.inspect %> => <%= target.inspect %> }
+
   # How long a username may be, in characters.
   # config.length          = 3..30
 

data/lib/usernames/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/integer/time"
+
 module Usernames
   # `Usernames.configure { |config| … }`. The generated initializer shows ten
   # of these options; the README documents the rest.
@@ -88,6 +90,89 @@ module Usernames
       end
     end
 
+    # config.availability: the built-in "is this name free?" endpoint. None
+    # of it is a rule, so nothing here touches the compiled rules.
+    class Availability
+      # The route drawn for the endpoint; nil or false draws none.
+      attr_accessor :path
+
+      # Which username columns the endpoint answers for, by an alias the
+      # browser sends: { "user" => "User#handle" }. Nothing else is ever
+      # looked up, so a model with has_username is not published by
+      # declaring it. The install generator writes yours.
+      attr_accessor :targets
+
+      # The class the endpoint inherits from, by name. nil: your
+      # ApplicationController when there is one (its locale and
+      # authentication callbacks apply), else ActionController::Base.
+      # "ActionController::API" works too.
+      attr_accessor :parent_controller
+
+      # Rails' rate_limit, per client IP: { to: 30, within: 1.minute }.
+      attr_accessor :rate_limit
+
+      # Where the rate limit counts. nil: Rails.cache. Read once, when the
+      # endpoint's class loads, so a change needs a restart.
+      attr_accessor :rate_limit_store
+
+      ALIAS = /\A[a-z0-9][a-z0-9_-]*\z/
+      TARGET = /\A[A-Z]\w*(?:::[A-Z]\w*)*#[a-z_]\w*\z/
+
+      def initialize
+        @path = Usernames::Routes::DEFAULT_PATH
+        @targets = {}.freeze
+        @parent_controller = nil
+        @rate_limit = { to: 30, within: 1.minute }.freeze
+        @rate_limit_store = nil
+      end
+
+      # The endpoint's superclass (see parent_controller). :nodoc:
+      def parent_class
+        name = parent_controller
+        name ||= Object.const_defined?(:ApplicationController) ? "ApplicationController" : "ActionController::Base"
+        Object.const_get(name)
+      end
+
+      def validate!
+        valid_path!
+        valid_targets!
+        unless parent_controller.nil? || (parent_controller.is_a?(String) && !parent_controller.empty?)
+          invalid!(:parent_controller, parent_controller, "a class name as a String, like \"ApplicationController\"")
+        end
+        valid_rate_limit!
+      end
+
+      private
+
+      def valid_path!
+        return if [nil, false].include?(path) || (path.is_a?(String) && path.match?(%r{\A/[^/?#\s]}))
+
+        invalid!(:path, path, "a path like \"/usernames/availability\", or nil to draw no route")
+      end
+
+      def valid_targets!
+        valid = targets.is_a?(Hash) && targets.all? do |name, target|
+          name.is_a?(String) && name.match?(ALIAS) && target.is_a?(String) && target.match?(TARGET)
+        end
+        return if valid
+
+        invalid!(:targets, targets, "a Hash of aliases to \"Model#column\" Strings, like { \"user\" => \"User#handle\" }")
+      end
+
+      def valid_rate_limit!
+        limit = rate_limit
+        valid = limit.is_a?(Hash) && limit.keys.sort == %i[to within] && limit[:to].is_a?(Integer) &&
+                limit[:to].positive? && limit[:within].is_a?(Numeric) && limit[:within].positive?
+        return if valid
+
+        invalid!(:rate_limit, limit, "{ to: 30, within: 1.minute }: a whole number of requests per period")
+      end
+
+      def invalid!(option, value, expected)
+        raise ConfigurationError, "config.availability.#{option} must be #{expected} (got #{value.inspect})"
+      end
+    end
+
     # Per-call word lists ADD to the configured ones: a model that passes
     # `reserved: %w[recipe]` keeps every bundled reservation. Every other
     # per-call option replaces the configured value. Adding is the choice
@@ -100,9 +185,9 @@ module Usernames
     CACHE_LIMIT = 64
 
     option :length, :separators, :edge_separators, :case, :first_character, :reserve_routes, :app_name,
-           :reserved, :forbidden, :allowed, :on_adapter_failure, :unique_index
+           :reserved, :forbidden, :allowed, :reserved_if, :on_adapter_failure, :unique_index
 
-    attr_reader :offensive, :generator
+    attr_reader :offensive, :generator, :availability
 
     def initialize
       @length = 3..30
@@ -115,10 +200,14 @@ module Usernames
       @reserved = Data.reserved
       @forbidden = Data.impersonation
       @allowed = [].freeze
+      # ->(name) { Page.exists?(slug: name) }: names reserved by your data
+      # rather than a list. nil: none.
+      @reserved_if = nil
       @on_adapter_failure = :allow
       @unique_index = nil
       @offensive = Offensive.new(self)
       @generator = Generator.new(self)
+      @availability = Availability.new
     end
 
     # `config.generator = ->(attempt) { … }` replaces the default shape;
@@ -140,6 +229,7 @@ module Usernames
 
     def validate!
       rules_for
+      availability.validate!
       self
     end
 
@@ -147,7 +237,7 @@ module Usernames
       {
         length: length, separators: separators, edge_separators: edge_separators, case: @case,
         first_character: first_character, reserve_routes: reserve_routes, app_name: app_name,
-        reserved: reserved, forbidden: forbidden, allowed: allowed, offensive: offensive.to_h,
+        reserved: reserved, forbidden: forbidden, allowed: allowed, reserved_if: reserved_if, offensive: offensive.to_h,
         on_adapter_failure: on_adapter_failure, generator: generator.to_h, unique_index: unique_index
       }
     end

data/lib/usernames/engine.rb

@@ -1,32 +1,93 @@
 # frozen_string_literal: true
 
+require_relative "form_helpers"
+require_relative "routes"
+
 module Usernames
-  # Not isolated, and no routes: the gem mounts nothing behind your back
-  # (the availability check is a generator that copies files into the app).
+  # Not isolated. What it wires into the app, and how to turn each piece off:
   #
-  # What it does do: its config/locales load BEFORE the app's — Rails puts
-  # engines first and the application last — so any key in the app's own
-  # locale files wins; `has_username` reaches every Active Record model; the
-  # app's own routes are reserved and re-read whenever they reload; and a bad
-  # configuration value fails at boot, not at the first sign-up.
+  # * `has_username` on every Active Record model.
+  # * Its config/locales, loaded BEFORE the app's — Rails puts engines first
+  #   and the application last — so any key in the app's own locale files
+  #   wins.
+  # * The app's own routes reserved, re-read whenever they reload
+  #   (config.reserve_routes = false turns it off).
+  # * The availability endpoint, Usernames::AvailabilityController, at
+  #   config.availability.path: one route appended after the app's own, and
+  #   left out when the app already has one named usernames_availability
+  #   (path = nil draws none).
+  # * `f.username_field` / `f.username_status` on every form builder.
+  # * With importmap-rails, the pins `usernames` and `usernames/username-check`;
+  #   with Propshaft or Sprockets, the JavaScript behind them. `import
+  #   "usernames"` in app/javascript/application.js is what uses them.
+  # * A bad configuration value fails at boot, not at the first sign-up.
   #
   # The generators (`usernames:install`, `usernames:availability`,
-  # `usernames:locale`) need no wiring: Rails finds them in
-  # lib/generators/usernames/ on the load path.
+  # `usernames:javascript`, `usernames:locale`) need no wiring: Rails finds
+  # them in lib/generators/usernames/ on the load path.
   class Engine < ::Rails::Engine
+    JAVASCRIPTS = %w[usernames/index.js usernames/username_check_controller.js].freeze
+
     initializer "usernames.active_record" do
       ActiveSupport.on_load(:active_record) { extend Usernames::Model }
     end
 
+    initializer "usernames.form_helpers" do
+      ActiveSupport.on_load(:action_view) { ActionView::Helpers::FormBuilder.include(Usernames::FormBuilder) }
+    end
+
+    # Once, before the routes are first drawn. The block runs on every
+    # draw (and redraw in development), reading the configuration as it is
+    # by then.
+    initializer "usernames.routes" do |app|
+      ActionDispatch::Routing::Mapper.include(Usernames::Routes)
+      routes = app.routes
+      routes.append { Usernames::Engine.draw_availability_route(self, routes) }
+    end
+
+    # Before importmap-rails reads its paths; nothing at all without it.
+    initializer "usernames.importmap", before: "importmap" do |app|
+      next unless defined?(::Importmap) && app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+
+    # Propshaft and Sprockets both find an engine's app/assets on their own;
+    # Sprockets also needs to be told to precompile them.
+    initializer "usernames.assets" do |app|
+      Usernames::Engine.add_assets(app.config.assets) if app.config.respond_to?(:assets) && app.config.assets
+    end
+
     # After every initializer, including the app's config/initializers/usernames.rb.
     initializer "usernames.validate_configuration" do |app|
       app.config.after_initialize { Usernames.configuration.validate! }
     end
 
-    # The app's static top-level paths are reserved. They are
-    # collected lazily, on the first check after the routes load; in
-    # development the routes reload when config/routes.rb changes, and a
-    # page added there is reserved from the next check on.
+    # The app's static top-level paths are reserved — the endpoint's own
+    # first segment (`usernames`) among them. They are collected lazily, on
+    # the first check after the routes load; in development the routes
+    # reload when config/routes.rb changes, and a page added there is
+    # reserved from the next check on.
     config.after_routes_loaded { Usernames::Reserved.reset_routes! }
+
+    class << self
+      # The appended route: drawn unless the path is off or the app drew one
+      # of that name itself. :nodoc:
+      def draw_availability_route(mapper, routes)
+        return unless Usernames.configuration.availability.path
+        return if routes.named_routes.key?(:usernames_availability)
+
+        mapper.usernames_availability
+      end
+
+      # :nodoc:
+      def add_assets(assets)
+        javascripts = root.join("app/assets/javascripts").to_s
+        paths = assets.paths
+        paths << javascripts if paths.is_a?(Array) && paths.none? { |path| path.to_s == javascripts }
+        assets.precompile |= JAVASCRIPTS if assets.precompile.is_a?(Array)
+      end
+    end
   end
 end

data/lib/usernames/form_helpers.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Usernames
+  # A username field with live hints and the availability check:
+  #
+  #   <%= form_with model: @user do |f| %>
+  #     <%= f.label :handle %>
+  #     <%= f.username_field :handle %>
+  #     <%= f.username_status :handle %>
+  #   <% end %>
+  #
+  # The field is a text field the `username-check` Stimulus controller
+  # watches; the status is the live region it writes to. While someone
+  # types, the field shows the first format rule the name breaks, then
+  # whether it is free. Nothing blocks submission: the model decides.
+  #
+  #   f.username_field :handle, availability: false   # format hints only, no request
+  #   f.username_field :handle, static: true          # a plain text field
+  #
+  # Every other option is the text field's, `class:` included.
+  # `data: { controller:, action: }` and `aria: { describedby: }` are joined
+  # with the field's own as token lists; the rest of `data:` and `aria:` is
+  # merged in, and the field's own `username-check-*` values are the field's.
+  #
+  # The input's id is `field_id(:handle)` (`user_handle`), the status's
+  # `field_id(:handle, :status)`. Two forms for the same record on one page
+  # need different ones: pass `namespace:` to form_with, or the same `id:`
+  # to both helpers.
+  module FormBuilder
+    def username_field(column = :username, availability: true, static: false, **html)
+      column = column.to_sym
+      html = Field.attributes(html)
+      return text_field(column, Field::TYPING.merge(html)) if static
+
+      own, input = username_field_ids(column, html)
+      check = Field.check(@template, object, column, id: input, availability: availability)
+      return text_field(column, Field::TYPING.merge(html)) if check.nil?
+
+      text_field(column, Field.combine(Field::TYPING.merge(html), check).merge(id: own))
+    end
+
+    # <output id="user_handle_status" for="user_handle" aria-live="polite">,
+    # empty until someone types; the controller sets its data-state
+    # (checking, free, taken, invalid, unchanged, error) for styling.
+    # Pass the field's `id:`, `namespace:` or `index:` here too if you gave it them.
+    def username_status(column = :username, **html)
+      html = Field.attributes(html)
+      _own, input = username_field_ids(column, html)
+      own = { id: "#{input}_status", for: input, aria: { "live" => "polite" } }
+      @template.tag.output("", **Field.combine(html.except(:id, :namespace, :index), own))
+    end
+
+    private
+
+    # The id the field gives Rails, and the id Rails renders from it. Given
+    # explicitly, so the input has the id the status points at even where
+    # form_with generates none; Rails prefixes the namespace to it (the
+    # field's own `namespace:`, else the form's), so this does too, and a
+    # field's own `index:` is in its id as in its name.
+    def username_field_ids(column, html)
+      own = html.fetch(:id) { field_id(column, namespace: nil, index: html.fetch(:index) { options[:index] }) }
+      [own, username_input_id(own, html.fetch(:namespace) { options[:namespace] })]
+    end
+
+    # An input's id as Rails renders it: the namespace, then the id.
+    def username_input_id(id, namespace)
+      namespace ? "#{namespace}_#{id}" : id
+    end
+  end
+
+  # The attributes behind the helpers. :nodoc:
+  module Field
+    # What tells a browser this is a username, not prose. Overridable:
+    # `autocomplete: "nickname"` for a public handle that isn't a login.
+    TYPING = { autocomplete: "username", autocapitalize: "none", autocorrect: "off", spellcheck: false }.freeze
+
+    # Space-separated lists, where the caller's values join the field's own.
+    TOKEN_LISTS = %w[data-controller data-action aria-describedby].freeze
+
+    NESTED = %w[data aria].freeze
+
+    MISSING_TARGET_LOGGED = Concurrent::AtomicBoolean.new(false)
+
+    class << self
+      # The data and aria attributes for a checked field, or nil when the
+      # field can only be plain (a production form whose column is not a target).
+      def check(template, object, column, id:, availability:)
+        model = model_of!(object, column)
+        endpoint = availability ? endpoint(template, model, column) : {}
+        return if endpoint == :missing
+
+        data = hints(object, model, column).merge("username-check-status-id-value" => "#{id}_status", **endpoint)
+        { data: data.compact, aria: { "describedby" => "#{id}_status" } }
+      end
+
+      # The form's model, which must have declared has_username for `column`.
+      def model_of!(object, column)
+        model = object.class
+        return model if model.respond_to?(:_usernames) && model._usernames.key?(column)
+
+        raise ArgumentError, "username_field :#{column} needs a form for a model with has_username :#{column} " \
+                             "(got #{object.inspect})"
+      end
+
+      # `data-…` and `aria-…` given as plain keys, moved into data: and
+      # aria:, so there is one place to merge them.
+      def attributes(html)
+        html.each_with_object({}) do |(key, value), attributes|
+          nested, name = key.to_s.split("-", 2)
+          if value.is_a?(Hash)
+            nested = key.to_s
+            value = value.transform_keys { |each| each.to_s.dasherize }
+          end
+          next attributes[key.to_sym] = value unless NESTED.include?(nested)
+
+          (attributes[nested.to_sym] ||= {}).merge!(name ? { name => value } : value)
+        end
+      end
+
+      # The caller's attributes with the field's own over them: token lists
+      # joined, data and aria merged (deeply), the field's values winning for
+      # its own keys.
+      def combine(theirs, ours)
+        theirs.merge(ours) do |key, given, own|
+          next own unless given.is_a?(Hash) && own.is_a?(Hash)
+
+          given.deep_merge(own) { |name, mine, field| token_list?("#{key}-#{name}") ? tokens(mine, field) : field }
+        end
+      end
+
+      private
+
+      # What the browser needs for its format hints: the rules (in the model's
+      # words), the case mode and the saved name. Every value a String, and
+      # the rules encoded by the json gem itself, so rendering a field never
+      # depends on Active Support's JSON encoder.
+      def hints(object, model, column)
+        {
+          "controller" => "username-check",
+          "action" => "input->username-check#check",
+          "username-check-rules-value" => JSON.generate(model.public_send(:"#{column}_rules_for_browser")),
+          "username-check-lowercase-value" => (model._usernames.fetch(column).mode != :preserve).to_s,
+          "username-check-persisted-value" => persisted(object, column)
+        }
+      end
+
+      # The endpoint's URL and this column's alias in config.availability.targets.
+      def endpoint(template, model, column)
+        url = url(template)
+        return {} if url.nil?
+
+        target = Targets.alias_for(model, column)
+        return missing_target(model, column) if target.nil?
+
+        { "username-check-url-value" => url, "username-check-target-value" => target,
+          "username-check-error-message-value" => error_message }
+      end
+
+      # In the page's language, else in English, never "Translation missing"
+      # (see Usernames::Locale).
+      def error_message
+        Locale.t(:usernames, :availability, :error)
+      end
+
+      # Through the app's route helper (`main_app` from inside an engine's
+      # views), so a sub-URI deployment's SCRIPT_NAME is in it. None when
+      # the app has no such route: the field then only hints.
+      def url(template)
+        routes = template.respond_to?(:main_app) ? template.main_app : template
+        routes.usernames_availability_path if routes.respond_to?(:usernames_availability_path)
+      end
+
+      # Publishing a column takes a line in config.availability.targets: in
+      # development and test, saying so loudly; in production, a plain
+      # field and one log line rather than a broken page.
+      def missing_target(model, column)
+        target = "#{model.name}##{column}"
+        why = "no entry in config.availability.targets names #{target}: add " \
+              "{ #{model.name.to_s.underscore.tr('/', '_').inspect} => #{target.inspect} } to it, or pass " \
+              "availability: false"
+        raise ConfigurationError, "username_field :#{column} can't check availability: #{why}" if Rails.env.local?
+
+        Rails.logger.error "[usernames] username_field :#{column} renders without its check: #{why}." if
+          MISSING_TARGET_LOGGED.make_true
+        :missing
+      end
+
+      def persisted(object, column)
+        object.attribute_in_database(column).presence if object.respond_to?(:persisted?) && object.persisted?
+      end
+
+      def token_list?(name)
+        TOKEN_LISTS.include?(name)
+      end
+
+      # Joined as Rails joins a token list (token_list, class_names): Arrays
+      # flattened, a Hash keeping the keys whose values are truthy, nil and
+      # false left out; then split on whitespace and deduplicated.
+      def tokens(*lists)
+        lists.flat_map { |list| token_values(list) }.flat_map { |value| value.to_s.split }.uniq.join(" ")
+      end
+
+      def token_values(value)
+        case value
+        when Hash then value.filter_map { |token, wanted| token if wanted }
+        when Array then value.flat_map { |each| token_values(each) }
+        when nil, false then []
+        else [value]
+        end
+      end
+    end
+  end
+end

data/lib/usernames/locale.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Usernames
+  # The gem's own messages that are not a record's errors — what the
+  # availability check says — looked up so they never read
+  # "Translation missing":
+  #
+  # 1. in the current locale, so the app's own translation wins;
+  # 2. else in English as I18n has it (the app's English wording, if any);
+  # 3. else in the gem's English, read from config/locales/usernames.en.yml
+  #    itself — for an app whose available locales leave English out, where
+  #    I18n never loads it.
+  #
+  # The YAML file stays the one place the words are written. :nodoc:
+  module Locale
+    ENGLISH = File.expand_path("../../config/locales/usernames.en.yml", __dir__)
+
+    class << self
+      # Locale.t(:usernames, :availability, :error) # => "couldn't be checked just now"
+      def t(*keys, key)
+        I18n.t(key, scope: keys, raise: true)
+      rescue I18n::MissingTranslationData
+        if I18n.backend.exists?(:en, key, scope: keys)
+          I18n.backend.translate(:en, key, scope: keys)
+        else
+          english(*keys, key)
+        end
+      end
+
+      # The gem's own English for these keys, from the shipped file.
+      def english(*keys)
+        @english ||= YAML.safe_load(File.read(ENGLISH, encoding: "UTF-8")).fetch("en").freeze
+        @english.dig(*keys.map(&:to_s))
+      end
+    end
+  end
+end