tam_select 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3f063f1d79268f900b10c4b86399cba1a34dac0154a90c4c12fd505771a1431
-  data.tar.gz: 0cf4fe7a1cf1d1dc479065318819db1ced4e71888e81e6c98a25fc6920841852
+  metadata.gz: 3cdee3c229caaeda5d7f572395009c1ffd03e58c1f5376c215ced0e751c35fb9
+  data.tar.gz: 9896dd22aa1dc9af3727596c1bee1d82ca6b8f1462a3e24a5177b10306853888
 SHA512:
-  metadata.gz: 8ad40f38121d3e83e9260c825c8bbd7546c62d87073fef14ef63c70fd027a1a08bcbd18d51d60198d3a06410b2e3c3ffd325182f99b9b08c1af7b23e725a70c3
-  data.tar.gz: 55469f46c8348ed51dff78070efe3ddf8b95ce43cb2ae3d5b299382bf80437022fe1f91066e07c2b4d061abfba0c984d892d958616692a02415c062e4cb622db
+  metadata.gz: 271d3b88383037c504189080665c0c15e19a640e6f8efe0d580683d9f543a0a56ff496a667064b788fbd8a8f1ddc8f48512d755cfc10985ec043d36c042891ce
+  data.tar.gz: be82081ad386749cb1ff40f1cd48ca80417104712c417de25dccc969082f3f2edfce09a912bce53467c34e170b1a0235245caede8d53717b7fff5d3b21d8f072

data/README.md

@@ -1,7 +1,7 @@
 the # Tam Select
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Gem Version](https://img.shields.io/badge/version-0.1.1-blue.svg)](https://github.com/tamiru/tam_select)
+[![Gem Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/tamiru/tam_select)
 
 **Tam Select** is an accessible, searchable select component for Ruby on Rails, built for Simple Form, Stimulus, Turbo, and Tailwind CSS. It keeps the native `<select>` as the source of truth, so Rails form submission, validation, selected values, and browser autofill continue to work.
 
@@ -36,6 +36,7 @@ app/javascript/tam_select/tam_select.js
 app/javascript/controllers/tam_select_controller.js
 app/inputs/tam_select_input.rb
 app/controllers/concerns/tam_select_paginatable.rb
+app/controllers/concerns/tam_select_remote.rb
 app/controllers/tam_select_remote_controller.rb
 app/helpers/tam_select_helper.rb
 ```
@@ -131,7 +132,9 @@ Stimulus destroys generated markup when Turbo removes the select and recreates i
 
 ## Simple Form
 
-The install generator creates `app/inputs/tam_select_input.rb`. Use it like any other Simple Form input:
+The install generator creates `app/inputs/tam_select_input.rb`. Use `as: :tam_select` with any Simple Form collection input.
+
+### Local collection
 
 ```erb
 <%= form.input :region_id,
@@ -139,16 +142,49 @@ The install generator creates `app/inputs/tam_select_input.rb`. Use it like any
       collection: Region.order(:name),
       label_method: :name,
       value_method: :id,
+      prompt: "Select region" %>
+```
+
+### Remote collection
+
+Keep the currently selected record in the initial collection so edit forms can display its label before the AJAX request completes:
+
+```erb
+<%= form.input :region_id,
+      as: :tam_select,
+      collection: [form.object.region].compact,
+      label_method: :name,
+      value_method: :id,
       prompt: "Select region",
       input_html: {
         tam_options: {
-          remoteUrl: region_options_path(format: :json),
-          minQueryLength: 1
+          remoteUrl: tam_select_options_regions_path(format: :json),
+          minQueryLength: 1,
+          debounce: 250
         }
       } %>
 ```
 
-For a many-to-many field, add `multiple: true` to `input_html`.
+The concern and route required by this example are described in [Add remote search to an existing controller](#add-remote-search-to-an-existing-controller).
+
+### Multiple selection
+
+```erb
+<%= form.input :skill_ids,
+      as: :tam_select,
+      collection: Skill.order(:name),
+      label_method: :name,
+      value_method: :id,
+      input_html: {
+        multiple: true,
+        tam_options: {
+          searchable: true,
+          closeAfterSelect: false
+        }
+      } %>
+```
+
+Options are passed under `input_html[:tam_options]`. Common options include `searchable`, `creatable`, `clearable`, `placeholder`, `searchPlaceholder`, `remoteUrl`, `minQueryLength`, and `debounce`. See [Main options](#main-options) for defaults.
 
 ## Remote API contract
 
@@ -172,6 +208,53 @@ The generator installs `TamSelectPaginatable` as a Rails response helper. A comp
 
 Secure remote endpoints exactly like other Rails JSON endpoints. Scope records by the current user's permissions and never trust a submitted value merely because it appeared in the dropdown.
 
+### Add remote search to an existing controller
+
+Include `TamSelectRemote` and declare the allowed model and searchable fields. This adds the public `tam_select_options` action to the controller:
+
+```ruby
+# app/controllers/regions_controller.rb
+class RegionsController < ApplicationController
+  include TamSelectRemote
+
+  tam_select_remote(
+    model: Region,
+    label: :name,
+    value: :id,
+    search_by: %i[name code],
+    scope: -> { Region.order(:name) },
+    per_page: 20
+  )
+end
+```
+
+The optional `scope` lambda runs in the controller context, so it can use `current_user`, `current_account`, or an authorization policy.
+
+```ruby
+# config/routes.rb
+resources :regions do
+  get :tam_select_options, on: :collection, defaults: { format: :json }
+end
+```
+
+Point Simple Form to that collection action:
+
+```erb
+<%= form.input :region_id,
+      as: :tam_select,
+      collection: [form.object.region].compact,
+      label_method: :name,
+      value_method: :id,
+      input_html: {
+        tam_options: {
+          remoteUrl: tam_select_options_regions_path(format: :json),
+          minQueryLength: 1
+        }
+      } %>
+```
+
+Typing sends `GET /regions/tam_select_options.json?q=addis&page=1` and receives the standard Tam Select JSON payload.
+
 ### Generic remote controller
 
 The installer generates `TamSelectRemoteController`. Create a small subclass for each allowed remote source:

data/lib/generators/tam_select/install_generator.rb

@@ -18,6 +18,7 @@ module TamSelect
 
       def copy_controller_concern
         copy_file "lib/generators/tam_select/templates/tam_select_paginatable.rb", "app/controllers/concerns/tam_select_paginatable.rb"
+        copy_file "lib/generators/tam_select/templates/tam_select_remote.rb", "app/controllers/concerns/tam_select_remote.rb"
       end
 
       def copy_remote_controller

data/lib/generators/tam_select/templates/tam_select_remote.rb

@@ -0,0 +1,54 @@
+module TamSelectRemote
+  extend ActiveSupport::Concern
+
+  included do
+    include TamSelectPaginatable
+    class_attribute :tam_select_remote_config, instance_writer: false
+  end
+
+  class_methods do
+    def tam_select_remote(model:, label:, value: :id, search_by: nil, scope: nil, per_page: 20)
+      self.tam_select_remote_config = {
+        model: model,
+        label: label,
+        value: value,
+        search_by: Array(search_by || label),
+        scope: scope,
+        per_page: per_page
+      }.freeze
+    end
+  end
+
+  def tam_select_options
+    config = tam_select_remote_config!
+    records = tam_select_remote_search(tam_select_remote_scope(config), config)
+
+    render json: tam_select_payload(
+      records,
+      label: config[:label],
+      value: config[:value],
+      per_page: config[:per_page]
+    )
+  end
+
+  private
+
+  def tam_select_remote_config!
+    self.class.tam_select_remote_config ||
+      raise("Configure #{self.class.name} with tam_select_remote(...)")
+  end
+
+  def tam_select_remote_scope(config)
+    config[:scope] ? instance_exec(&config[:scope]) : config[:model].all
+  end
+
+  def tam_select_remote_search(records, config)
+    query = params[:q].to_s.strip
+    return records if query.blank?
+
+    model = config[:model]
+    pattern = "%#{model.sanitize_sql_like(query)}%"
+    predicates = config[:search_by].map { |field| model.arel_table[field].matches(pattern) }
+    records.where(predicates.reduce(&:or))
+  end
+end

data/lib/generators/tam_select/templates/tam_select_remote_controller.rb

@@ -1,44 +1,6 @@
 class TamSelectRemoteController < ApplicationController
-  include TamSelectPaginatable
+  include TamSelectRemote
 
-  class_attribute :tam_select_config, instance_writer: false
-
-  def self.tam_select(model:, label:, value: :id, search_by: nil, per_page: 20)
-    self.tam_select_config = {
-      model: model,
-      label: label,
-      value: value,
-      search_by: Array(search_by || label),
-      per_page: per_page
-    }.freeze
-  end
-
-  def index
-    config = self.class.tam_select_config
-    raise "Configure #{self.class.name} with tam_select(...)" unless config
-
-    records = search(tam_select_scope(config), config)
-    render json: tam_select_payload(
-      records,
-      label: config[:label],
-      value: config[:value],
-      per_page: config[:per_page]
-    )
-  end
-
-  private
-
-  def tam_select_scope(config)
-    config[:model].all
-  end
-
-  def search(records, config)
-    query = params[:q].to_s.strip
-    return records if query.blank?
-
-    model = config[:model]
-    pattern = "%#{model.sanitize_sql_like(query)}%"
-    predicates = config[:search_by].map { |field| model.arel_table[field].matches(pattern) }
-    records.where(predicates.reduce(&:or))
-  end
+  # Configure this base controller in a subclass, or include TamSelectRemote
+  # directly in an existing resource controller. See the Tam Select README.
 end

data/lib/tam_select/version.rb

@@ -1,3 +1,3 @@
 module TamSelect
-  VERSION = "1.0.0"
+  VERSION = "1.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tam_select
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Tamiru Hailu
@@ -62,6 +62,7 @@ files:
 - lib/generators/tam_select/templates/tam_select_helper.rb
 - lib/generators/tam_select/templates/tam_select_input.rb
 - lib/generators/tam_select/templates/tam_select_paginatable.rb
+- lib/generators/tam_select/templates/tam_select_remote.rb
 - lib/generators/tam_select/templates/tam_select_remote_controller.rb
 - lib/tam_select.rb
 - lib/tam_select/engine.rb