tam_select 0.1.1 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3a066f1e145b6a880f28494f78c00d51c1ca280fc984975c2eebf849704041c
-  data.tar.gz: 1537eeda1e3dda9a3a38077bbfe6076cc9d851e6b404345188b61b845fd3107a
+  metadata.gz: 3cdee3c229caaeda5d7f572395009c1ffd03e58c1f5376c215ced0e751c35fb9
+  data.tar.gz: 9896dd22aa1dc9af3727596c1bee1d82ca6b8f1462a3e24a5177b10306853888
 SHA512:
-  metadata.gz: 454ff7b7e777da2409741dff572ead04fc84ae5e65be2984c44d9c0196924ecf6d695e7445d23cbb7ba683abea8bf7e821f79e06cac71da9e4c8c6a718f8c823
-  data.tar.gz: f5950761f9e589454f4dad82e2ed52dbe5ac88d5856a8ee133da81916bf5e5ec20c8e434e23aca8a868b8d9cce4612d5926929e1ef4643e9c4d597541c3b943e
+  metadata.gz: 271d3b88383037c504189080665c0c15e19a640e6f8efe0d580683d9f543a0a56ff496a667064b788fbd8a8f1ddc8f48512d755cfc10985ec043d36c042891ce
+  data.tar.gz: be82081ad386749cb1ff40f1cd48ca80417104712c417de25dccc969082f3f2edfce09a912bce53467c34e170b1a0235245caede8d53717b7fff5d3b21d8f072

data/README.md

@@ -1,6 +1,7 @@
-# Tam Select
+the # Tam Select
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![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.
 
@@ -35,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
 ```
@@ -48,6 +50,23 @@ Add the generated JavaScript to Tailwind's source detection in `app/assets/tailw
 @source "../../javascript/tam_select/**/*.js";
 ```
 
+### Updating
+
+The Rails integration files are copied into your application, so updating the gem does not update them automatically. Commit local customizations first, then run:
+
+```bash
+bundle update tam_select
+bin/rails generate tam_select:install
+```
+
+Rails prompts before replacing changed files. To replace every generated file without prompting, use:
+
+```bash
+bin/rails generate tam_select:install --force
+```
+
+Review `git diff` afterward because `--force` overwrites application-specific customizations.
+
 ## Features
 
 - Single and multiple selection
@@ -113,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,
@@ -121,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: regions_path,
-          minQueryLength: 1
+          remoteUrl: tam_select_options_regions_path(format: :json),
+          minQueryLength: 1,
+          debounce: 250
+        }
+      } %>
+```
+
+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
         }
       } %>
 ```
 
-For a many-to-many field, add `multiple: true` to `input_html`.
+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
 
@@ -154,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:
@@ -187,7 +288,7 @@ get "region_options", to: "region_options#index", defaults: { format: :json }
       value_method: :id,
       input_html: {
         tam_options: {
-          remoteUrl: region_options_path,
+          remoteUrl: region_options_path(format: :json),
           minQueryLength: 1
         }
       } %>
@@ -195,6 +296,22 @@ get "region_options", to: "region_options#index", defaults: { format: :json }
 
 Do not accept a model name from request parameters. Declaring each source in a controller subclass prevents clients from querying arbitrary application models.
 
+The browser sends requests such as:
+
+```text
+GET /region_options.json?q=addis&page=1
+Accept: application/json
+```
+
+Test an endpoint independently with:
+
+```bash
+curl -H "Accept: application/json" \
+  "http://localhost:3000/region_options.json?q=addis&page=1"
+```
+
+A `406 Not Acceptable` response means the route or controller rejected JSON. Keep `defaults: { format: :json }` on the route, use a `.json` URL, and ensure the controller does not restrict responses to HTML only.
+
 ## Core JavaScript
 
 ```js

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 = "0.1.1"
+  VERSION = "1.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tam_select
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  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